@artemiskit/core 0.5.2 → 0.6.0

package/src/agent-workflow/simulated-tools.ts

@@ -0,0 +1,230 @@
+import Ajv from 'ajv';
+import { getWorkflowTool, listWorkflowTools } from './catalog';
+import {
+  type WorkflowJson,
+  type WorkflowPolicy,
+  WorkflowPolicySchema,
+  isWorkflowJson,
+  isWorkflowRelativePath,
+} from './schema';
+
+type JsonObject = { [key: string]: WorkflowJson };
+type ToolFailureCode =
+  | 'undeclared_tool'
+  | 'permission_denied'
+  | 'invalid_input'
+  | 'invalid_state'
+  | 'not_found'
+  | 'output_limit'
+  | 'invalid_policy'
+  | 'tool_error';
+export interface SimulatedToolEvidence {
+  tool: string;
+  version: '1';
+  status: 'succeeded' | 'denied' | 'invalid' | 'failed';
+  code?: ToolFailureCode;
+}
+export type SimulatedToolResult =
+  | {
+      status: 'succeeded';
+      output: WorkflowJson;
+      state: JsonObject;
+      evidence: SimulatedToolEvidence;
+    }
+  | {
+      status: 'denied' | 'invalid' | 'failed';
+      code: ToolFailureCode;
+      evidence: SimulatedToolEvidence;
+    };
+
+const ajv = new Ajv({ allErrors: false, strict: true });
+const validators = new Map(
+  listWorkflowTools().map((tool) => [
+    tool.id,
+    { input: ajv.compile(tool.inputSchema), output: ajv.compile(tool.outputSchema) },
+  ])
+);
+
+function isObject(value: unknown): value is JsonObject {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+class SimulatedFailure extends Error {
+  constructor(readonly code: ToolFailureCode) {
+    super(code);
+  }
+}
+
+function objectAt(state: JsonObject, key: string, create = false): JsonObject {
+  const value = state[key];
+  if (value === undefined) {
+    const empty = {};
+    if (create) state[key] = empty;
+    return empty;
+  }
+  if (!isObject(value)) throw new SimulatedFailure('invalid_state');
+  return value;
+}
+
+function nextId(collection: JsonObject, prefix: string): string {
+  let index = Object.keys(collection).length + 1;
+  while (Object.hasOwn(collection, `${prefix}-${index}`)) index++;
+  return `${prefix}-${index}`;
+}
+
+/**
+ * One deterministic simulated call, with isolated input/output state and metadata-only evidence.
+ * Budgets are declarative here: a future environment runner owns action counts and deadlines.
+ * `side_effects` governs external effects; declared local state writes never authorize real effects.
+ */
+export function executeSimulatedTool(request: {
+  tool: string;
+  input: unknown;
+  state: unknown;
+  policy: WorkflowPolicy;
+  declaredTools: readonly string[];
+}): SimulatedToolResult {
+  const tool = getWorkflowTool(request.tool);
+  const evidenceTool = tool?.id ?? 'unknown';
+  function failure(
+    status: 'denied' | 'invalid' | 'failed',
+    code: ToolFailureCode
+  ): SimulatedToolResult {
+    return { status, code, evidence: { tool: evidenceTool, version: '1', status, code } };
+  }
+  if (!tool || !request.declaredTools.includes(tool.id))
+    return failure('denied', 'undeclared_tool');
+  if (!isWorkflowJson(request.policy)) return failure('denied', 'invalid_policy');
+  const policy = WorkflowPolicySchema.safeParse(request.policy);
+  if (!policy.success) return failure('denied', 'invalid_policy');
+  if (tool.authority.access !== 'none') {
+    const resource = tool.authority.resource as keyof WorkflowPolicy['permissions'];
+    const grant = policy.data.permissions[resource];
+    if (!grant || (tool.authority.access === 'write' && grant !== 'write'))
+      return failure('denied', 'permission_denied');
+  }
+  const validator = validators.get(tool.id);
+  if (
+    !validator ||
+    !isWorkflowJson(request.input) ||
+    !isObject(request.input) ||
+    !validator.input(request.input)
+  )
+    return failure('invalid', 'invalid_input');
+  if (!isWorkflowJson(request.state) || !isObject(request.state))
+    return failure('invalid', 'invalid_state');
+  const state: JsonObject = structuredClone(request.state);
+  const input = request.input;
+  let output: WorkflowJson;
+  try {
+    switch (tool.id) {
+      case 'search': {
+        const documents = objectAt(state, 'documents');
+        if (Object.values(documents).some((value) => typeof value !== 'string'))
+          throw new SimulatedFailure('invalid_state');
+        output = {
+          matches: Object.entries(documents)
+            .filter(([, content]) =>
+              (content as string).toLowerCase().includes((input.query as string).toLowerCase())
+            )
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .slice(0, 100)
+            .map(([id]) => ({ id })),
+        };
+        break;
+      }
+      case 'read_document': {
+        const content = objectAt(state, 'documents')[input.id as string];
+        if (content === undefined) throw new SimulatedFailure('not_found');
+        if (typeof content !== 'string') throw new SimulatedFailure('invalid_state');
+        output = { id: input.id, content };
+        break;
+      }
+      case 'query_records': {
+        const records = objectAt(state, 'records')[input.collection as string];
+        if (records === undefined) throw new SimulatedFailure('not_found');
+        if (!Array.isArray(records) || records.some((record) => !isObject(record)))
+          throw new SimulatedFailure('invalid_state');
+        output = { records: records.slice(0, 100) };
+        break;
+      }
+      case 'read_file':
+      case 'write_file': {
+        const path = input.path as string;
+        if (!isWorkflowRelativePath(path)) return failure('invalid', 'invalid_input');
+        const files = objectAt(state, 'files', tool.id === 'write_file');
+        if (tool.id === 'write_file') {
+          files[path] = input.content;
+          output = { path, written: true };
+        } else {
+          const content = files[path];
+          if (content === undefined) throw new SimulatedFailure('not_found');
+          if (typeof content !== 'string') throw new SimulatedFailure('invalid_state');
+          output = { content };
+        }
+        break;
+      }
+      case 'calculator': {
+        const a = input.a as number;
+        const b = input.b as number;
+        const value =
+          input.operation === 'add'
+            ? a + b
+            : input.operation === 'subtract'
+              ? a - b
+              : input.operation === 'multiply'
+                ? a * b
+                : a / b;
+        if (!Number.isFinite(value)) throw new SimulatedFailure('tool_error');
+        output = { value };
+        break;
+      }
+      case 'get_workflow_state':
+        output = { state: objectAt(state, 'workflow_state') };
+        break;
+      case 'request_approval': {
+        const workflow = objectAt(state, 'workflow_state', true);
+        workflow.approvals = { requested: true, status: 'pending', reason: input.reason };
+        output = { requested: true, status: 'pending' };
+        break;
+      }
+      case 'record_decision': {
+        objectAt(state, 'workflow_state', true).decision = input.decision;
+        output = { recorded: true };
+        break;
+      }
+      case 'draft_message': {
+        const drafts = objectAt(state, 'drafts', true);
+        const id = nextId(drafts, 'draft');
+        drafts[id] = { recipient: input.recipient, body: input.body, status: 'draft' };
+        output = { id, status: 'draft' };
+        break;
+      }
+      case 'delegate_task': {
+        const tasks = objectAt(state, 'tasks', true);
+        const id = nextId(tasks, 'task');
+        tasks[id] = { task: input.task, status: 'pending' };
+        output = { id, status: 'pending' };
+        break;
+      }
+      case 'get_task_status': {
+        const task = objectAt(state, 'tasks')[input.id as string];
+        if (task === undefined) throw new SimulatedFailure('not_found');
+        if (!isObject(task)) throw new SimulatedFailure('invalid_state');
+        output = { id: input.id, status: task.status };
+        break;
+      }
+    }
+    if (!isWorkflowJson(output) || !isWorkflowJson(state) || !validator.output(output))
+      return failure('failed', 'output_limit');
+    // Do not let consumers mutate returned state through a shared output reference.
+    return {
+      status: 'succeeded',
+      output: structuredClone(output),
+      state,
+      evidence: { tool: tool.id, version: '1', status: 'succeeded' },
+    };
+  } catch (error) {
+    return failure('failed', error instanceof SimulatedFailure ? error.code : 'tool_error');
+  }
+}

package/src/agent-workflow/target.test.ts

@@ -0,0 +1,276 @@
+import { describe, expect, test } from 'bun:test';
+import type { GenerateOptions, GenerateResult, ModelClient } from '../adapters/types';
+import { type AgentTurnRequest, createModelClientTarget } from './target';
+
+const request: AgentTurnRequest = {
+  messages: [{ role: 'user', content: 'Read the declared document.' }],
+  tools: [
+    {
+      type: 'function',
+      function: {
+        name: 'read_document',
+        parameters: {
+          type: 'object',
+          properties: { id: { type: 'string' } },
+          required: ['id'],
+          additionalProperties: false,
+        },
+      },
+    },
+  ],
+  model: 'requested-model',
+  generation: { maxTokens: 200, temperature: 0, topP: 1, seed: 1, stop: ['END'] },
+  budgets: { timeoutMs: 1000, maxToolCalls: 2 },
+};
+const call = {
+  id: 'call-1',
+  type: 'function' as const,
+  function: { name: 'read_document', arguments: '{"id":"doc-1"}' },
+};
+const response: GenerateResult = {
+  id: 'response-1',
+  model: 'observed-model',
+  text: '',
+  tokens: { prompt: 10, completion: 2, total: 12 },
+  latencyMs: 1,
+  finishReason: 'tool_calls',
+  toolCalls: [call],
+  raw: { secret: 'not-retained' },
+};
+function client(overrides: Partial<ModelClient> = {}): ModelClient {
+  return {
+    provider: 'custom-provider',
+    capabilities: async () => ({
+      streaming: false,
+      functionCalling: true,
+      toolUse: true,
+      maxContext: 1000,
+    }),
+    generate: async () => structuredClone(response),
+    ...overrides,
+  };
+}
+
+describe('ModelClient agent target', () => {
+  test('reports advertised capability and honest cancellation support', async () => {
+    expect(await createModelClientTarget(client()).capabilities({ timeoutMs: 100 })).toEqual({
+      status: 'available',
+      toolUse: true,
+      transportCancellation: false,
+    });
+  });
+  test('passes declared settings and returns normalized evidence without raw payloads', async () => {
+    let received: GenerateOptions | undefined;
+    const target = createModelClientTarget(
+      client({
+        generate: async (options) => {
+          received = options;
+          return response;
+        },
+      })
+    );
+    const result = await target.turn(request);
+    expect(received).toEqual({
+      prompt: request.messages,
+      tools: request.tools,
+      model: request.model,
+      ...request.generation,
+    });
+    expect(result).toEqual({
+      status: 'completed',
+      id: response.id,
+      model: response.model,
+      message: { role: 'assistant', content: '', tool_calls: [call] },
+      tokens: response.tokens,
+      latencyMs: 1,
+      finishReason: 'tool_calls',
+    });
+    expect(JSON.stringify(result)).not.toContain('not-retained');
+  });
+  test('accepts correlated tool results and preserves IDs into continuation', async () => {
+    let received: GenerateOptions | undefined;
+    const target = createModelClientTarget(
+      client({
+        generate: async (options) => {
+          received = options;
+          return { ...response, text: 'Done', toolCalls: undefined, finishReason: 'stop' };
+        },
+      })
+    );
+    const messages: AgentTurnRequest['messages'] = [
+      ...request.messages,
+      { role: 'assistant', content: '', tool_calls: [call] },
+      { role: 'tool', content: 'Document text', toolCallId: call.id },
+    ];
+    expect((await target.turn({ ...request, messages })).status).toBe('completed');
+    expect(received?.prompt).toEqual(messages);
+  });
+  test('unsupported capabilities prevent generate calls', async () => {
+    let generated = false;
+    const target = createModelClientTarget(
+      client({
+        capabilities: async () => ({
+          streaming: false,
+          functionCalling: false,
+          toolUse: false,
+          maxContext: 1000,
+        }),
+        generate: async () => {
+          generated = true;
+          return response;
+        },
+      })
+    );
+    expect(await target.turn(request)).toEqual({
+      status: 'unsupported',
+      code: 'tool_use_unsupported',
+    });
+    expect(generated).toBe(false);
+  });
+  test('capability errors and provider errors do not expose raw exception content', async () => {
+    for (const method of ['capabilities', 'generate'] as const) {
+      const target = createModelClientTarget(
+        client({
+          [method]: async () => {
+            throw new Error('secret provider credential');
+          },
+        })
+      );
+      expect(await target.turn(request)).toEqual({ status: 'error', code: 'target_error' });
+    }
+  });
+  test.each([
+    [
+      'unknown tool',
+      { toolCalls: [{ ...call, function: { ...call.function, name: 'send_money' } }] },
+    ],
+    ['duplicate ID', { toolCalls: [call, call] }],
+    [
+      'invalid JSON',
+      { toolCalls: [{ ...call, function: { ...call.function, arguments: 'broken' } }] },
+    ],
+    [
+      'nonobject arguments',
+      { toolCalls: [{ ...call, function: { ...call.function, arguments: '[]' } }] },
+    ],
+    [
+      'invalid schema arguments',
+      { toolCalls: [{ ...call, function: { ...call.function, arguments: '{"id":3}' } }] },
+    ],
+    ['negative usage', { tokens: { prompt: -1, completion: 2, total: 1 } }],
+    ['inconsistent usage', { tokens: { prompt: 1, completion: 2, total: 5 } }],
+    ['missing calls', { toolCalls: undefined }],
+    ['legacy function call', { functionCall: { name: 'read_document', arguments: '{}' } }],
+    ['invalid latency', { latencyMs: Number.NaN }],
+    ['missing observed model', { model: '' }],
+  ])('rejects malformed response: %s', async (_name, override) => {
+    const target = createModelClientTarget(
+      client({ generate: async () => ({ ...response, ...override }) })
+    );
+    expect(await target.turn(request)).toEqual({ status: 'invalid', code: 'invalid_response' });
+  });
+  test('rejects tool calls beyond the declared per-turn budget', async () => {
+    expect(
+      await createModelClientTarget(client()).turn({
+        ...request,
+        budgets: { ...request.budgets, maxToolCalls: 0 },
+      })
+    ).toEqual({ status: 'invalid', code: 'invalid_response' });
+  });
+  test('rejects async tool argument schemas before provider invocation', async () => {
+    let reached = false;
+    const target = createModelClientTarget(
+      client({
+        generate: async () => {
+          reached = true;
+          return response;
+        },
+      })
+    );
+    const tool = request.tools[0];
+    expect(
+      await target.turn({
+        ...request,
+        tools: [
+          {
+            ...tool,
+            function: {
+              ...tool.function,
+              parameters: { ...tool.function.parameters, $async: true },
+            },
+          },
+        ],
+      })
+    ).toEqual({ status: 'invalid', code: 'invalid_request' });
+    expect(reached).toBe(false);
+  });
+  test.each([
+    { budgets: { timeoutMs: 0, maxToolCalls: 2 } },
+    { generation: { maxTokens: -1 } },
+    { messages: [{ role: 'tool', content: 'Orphan', toolCallId: 'missing' }] },
+    { messages: [{ role: 'assistant', content: '', tool_calls: [call] }] },
+    { tools: [request.tools[0], request.tools[0]] },
+  ])('invalid request never reaches provider', async (override) => {
+    let reached = false;
+    const target = createModelClientTarget(
+      client({
+        generate: async () => {
+          reached = true;
+          return response;
+        },
+      })
+    );
+    expect(await target.turn({ ...request, ...override } as AgentTurnRequest)).toEqual({
+      status: 'invalid',
+      code: 'invalid_request',
+    });
+    expect(reached).toBe(false);
+  });
+  test('aborting before a turn prevents a provider call', async () => {
+    const controller = new AbortController();
+    controller.abort();
+    expect(await createModelClientTarget(client()).turn(request, controller.signal)).toEqual({
+      status: 'error',
+      code: 'aborted',
+    });
+  });
+  test('timeout bounds waiting even when generation does not settle', async () => {
+    const target = createModelClientTarget(client({ generate: () => new Promise(() => {}) }));
+    expect(await target.turn({ ...request, budgets: { timeoutMs: 10, maxToolCalls: 2 } })).toEqual({
+      status: 'error',
+      code: 'timeout',
+    });
+  });
+  test('capabilities settling after timeout cannot start generation', async () => {
+    let release: (() => void) | undefined;
+    let generated = false;
+    const target = createModelClientTarget(
+      client({
+        capabilities: async () => {
+          await new Promise<void>((resolve) => {
+            release = resolve;
+          });
+          return { streaming: false, functionCalling: true, toolUse: true, maxContext: 1 };
+        },
+        generate: async () => {
+          generated = true;
+          return response;
+        },
+      })
+    );
+    expect(await target.turn({ ...request, budgets: { timeoutMs: 10, maxToolCalls: 2 } })).toEqual({
+      status: 'error',
+      code: 'timeout',
+    });
+    release?.();
+    await new Promise((resolve) => setTimeout(resolve, 1));
+    expect(generated).toBe(false);
+  });
+  test('abort while waiting returns an explicit aborted result', async () => {
+    const controller = new AbortController();
+    const target = createModelClientTarget(client({ generate: () => new Promise(() => {}) }));
+    const pending = target.turn(request, controller.signal);
+    controller.abort();
+    expect(await pending).toEqual({ status: 'error', code: 'aborted' });
+  });
+});