feat(interaction): an interaction function calls a tool and answers with its result

capabilities/computation/src/capability/computation-function.ts

@@ -2,14 +2,14 @@ import {
   defineCapability,
   functionCategoryLabels,
   functionResourceLabels,
-  inWords,
+  outputInWords,
   type DefinitionSummary,
   type Capability,
 } from '@beonauto/definitions';
 import { issueText } from '@beonauto/definitions/document';
-import { asSentence, InvalidInput } from '@beonauto/operations';
+import { InvalidInput } from '@beonauto/operations';
 import type { ProgramPool } from '@beonauto/workflow-engine/dsl';
-import { Effect, Result, type Schema } from 'effect';
+import { Effect, Result } from 'effect';
 
 import type { ComputationFunctionDefinitionDocument } from '../document/computation-document.ts';
 import { parseComputationDocument } from '../document/document-parsing.ts';
@@ -42,13 +42,6 @@ function summarize({ description, input, output }: ComputationFunctionDefinition
   };
 }
 
-function describeResult(output: Schema.Json): string {
-  const words = inWords(output);
-  return words === undefined
-    ? 'Its result is too long to repeat here; the whole of it is in the details below.'
-    : asSentence(`Its result: ${words}`);
-}
-
 export function makeComputationFunctionAdapter({
   pool,
   deadlineMs = computationBounds.deadlineMs,
@@ -59,7 +52,7 @@ export function makeComputationFunctionAdapter({
     title: functionCategoryLabels.computation,
     guide: { name: 'computation-function' },
     noun: { one: functionResourceLabels.computation.singular, other: functionResourceLabels.computation.plural },
-    describeOutput: describeResult,
+    describeOutput: outputInWords('result'),
     mediaType: 'text/markdown',
     parse,
     summarize,

capabilities/coordination/src/calls/function-run.ts

@@ -5,7 +5,7 @@ import type {
   Lineage,
   RejectionKind,
   RejectionReason,
-  UnavailableBecause,
+  RejectionBecause,
 } from '@beonauto/operations';
 import type { Effect, Schema } from 'effect';
 
@@ -31,7 +31,7 @@ export type EndedRunResult =
       readonly detail: string;
       readonly issues?: readonly Issue[];
       readonly kind?: RejectionKind;
-      readonly because?: UnavailableBecause;
+      readonly because?: RejectionBecause;
     }
   | { readonly status: 'failed'; readonly detail: string };
 

capabilities/coordination/src/capability/workflow.ts

@@ -1,5 +1,11 @@
-import { defineCapability, inWords, type RunContext, type FinishesLater, type Capability } from '@beonauto/definitions';
-import { asSentence, Conflict, type InvalidInput, type Unavailable } from '@beonauto/operations';
+import {
+  defineCapability,
+  outputInWords,
+  type RunContext,
+  type FinishesLater,
+  type Capability,
+} from '@beonauto/definitions';
+import { Conflict, type InvalidInput, type Unavailable } from '@beonauto/operations';
 import type { StartAnswer, WorkflowHost } from '@beonauto/workflow-host';
 import { Effect, Random, type Schema } from 'effect';
 
@@ -22,13 +28,6 @@ const notNow = 'The workflow cannot start now; try again shortly';
 
 const mostSeed = 2_147_483_647;
 
-function describeResult(output: Schema.Json): string {
-  const words = inWords(output);
-  return words === undefined
-    ? 'Its result is too long to repeat here; the whole of it is in the details below.'
-    : asSentence(`Its result: ${words}`);
-}
-
 function finishedLaterOr(answer: StartAnswer): Effect.Effect<FinishesLater, Conflict> {
   return answer === 'settled'
     ? Effect.fail(new Conflict({ detail: ranBefore, kind: 'unworkable' }))
@@ -68,7 +67,7 @@ export function makeWorkflowAdapter(dependencies: WorkflowAdapterDependencies):
     title: 'Workflow',
     guide: { name: 'workflow' },
     noun: { one: 'workflow', other: 'workflows' },
-    describeOutput: describeResult,
+    describeOutput: outputInWords('result'),
     mediaType: 'application/yaml',
     parse: (source: string): Effect.Effect<WorkflowDefinitionDocument, InvalidInput> =>
       parseWorkflowDocument(source, dependencies.mostDurationMs),

capabilities/coordination/src/presenting/run-presenter.test.ts

@@ -135,16 +135,17 @@ describe('the words of an input a workflow took', () => {
   });
 });
 
-function rejectedWith(kind: string, because: string): InputReceipt {
-  return { kind: 'call_answered', key: callKeyText(callKey), at, status: 'rejected', rejection: { kind, because } };
+function rejectedWith(kind: string, because?: string): InputReceipt {
+  const rejection = because === undefined ? { kind } : { kind, because };
+  return { kind: 'call_answered', key: callKeyText(callKey), at, status: 'rejected', rejection };
 }
 
 describe('the words of a rejection of a function a workflow called', () => {
   it('says why it did not succeed in plain words, after what happened', () => {
     expect(
       present(recordOf(eventOf(rejectedWith('tools_unfinished', 'server_failed'), stepsOf(1), [settled])))?.summary,
     ).toBe(
-      'A function the workflow called did not succeed, and 1 step moved; the workflow ended. It called tools but could not finish, because a tool server kept failing.',
+      'A function the workflow called did not succeed, and 1 step moved; the workflow ended. It called tools but could not finish, because a tool server failed.',
     );
   });
 
@@ -158,9 +159,13 @@ describe('the words of a rejection of a function a workflow called', () => {
       'A function the workflow called did not succeed. A tool server it needs could not be used, because the tool server asked it to slow down for longer than a run waits.',
     ],
     [
-      rejectedWith('tools_called', 'no_answer'),
+      rejectedWith('tools_called'),
       'A function the workflow called did not succeed. This run calls tools, and an attempt of it under the same id may still be in progress or did not succeed, so its tools may have changed something.',
     ],
+    [
+      rejectedWith('effect_unknown', 'server_failed'),
+      'A function the workflow called did not succeed. It could not finish after calling a tool that may change something, so whether that happened is not known, because a tool server failed.',
+    ],
     [rejectedWith('something_new', 'some_reason'), 'A function the workflow called did not succeed.'],
   ])('says each kind and because it knows: %#', (receipt, summary) => {
     expect(present(recordOf(eventOf(receipt)))?.summary).toBe(summary);

capabilities/coordination/src/presenting/run-words.ts

@@ -2,7 +2,7 @@ import {
   CancelledKindSchema,
   ConflictKindSchema,
   UnansweredKindSchema,
-  UnavailableBecauseSchema,
+  RejectionBecauseSchema,
   UnavailableKindSchema,
   asSentence,
   capitalized,
@@ -43,7 +43,7 @@ const decodeCancelledKind = Schema.decodeUnknownOption(CancelledKindSchema);
 
 const decodeUnansweredKind = Schema.decodeUnknownOption(UnansweredKindSchema);
 
-const decodeBecause = Schema.decodeUnknownOption(UnavailableBecauseSchema);
+const decodeBecause = Schema.decodeUnknownOption(RejectionBecauseSchema);
 
 type Rejection = NonNullable<Extract<InputReceipt, { readonly kind: 'call_answered' }>['rejection']>;
 
@@ -56,7 +56,7 @@ function whyNot({ kind, because }: Rejection): string {
   }
   const conflict = Option.getOrUndefined(decodeConflictKind(kind));
   if (conflict !== undefined) {
-    return explanationOf({ reason: 'conflict', kind: conflict }).why;
+    return explanationOf({ reason: 'conflict', kind: conflict, ...withBecause }).why;
   }
   const cancelled = Option.getOrUndefined(decodeCancelledKind(kind));
   if (cancelled !== undefined) {