Chapter 3: Agency

// 1. Ask the model what to do
const response = await llm.complete([
  {
    role: 'system',
    content:
      'When sending email, reply with format: SEND_EMAIL <recipient> <message>.',
  },
  {
    role: 'user',
    content: 'Please email alice@example.com: "Hello Alice"',
  },
]);

// 2. Naive, unsafe interpretation:
//    Look for a magic phrase in the text and act on it.
if (response.text.startsWith('SEND_EMAIL ')) {
  const [_, to, ...bodyParts] = response.text.split(' ');
  const body = bodyParts.join(' ');

  await sendEmail({ to, body }); // <-- This line causes the real-world effect
}

// 1. Define the tools and their parameter schemas
const tools = {
  sendEmail: {
    description: 'Send a plain-text email to a single recipient.',
    schema: z.object({
      to: z.string().email(),
      subject: z.string(),
      body: z.string(),
    }),
    async execute(args: { to: string; subject: string; body: string }) {
      return await emailClient.send(args); // real effect happens here
    },
  },
} as const;

// 2. Call the model, advertising the tools in context
const modelResponse = await llm.complete(
  [
    {
      role: 'system',
      content: 'You can call tools to perform actions. Think step by step.',
    },
    {
      role: 'user',
      content: 'Email alice@example.com with subject "Hi" and body "Hello Alice."',
    },
  ],
  {
    tools: Object.entries(tools).map(([name, def]) => ({
      name,
      description: def.description,
      schema: def.schema, // serialized schema
    })),
  },
);

// 3. The model outputs JSON *as text*
const toolCallText = modelResponse.toolCallJson; // e.g. '{"tool":"sendEmail","arguments":{...}}'

// 4. Your router interprets and executes it
async function handleToolCall(json: string) {
  const { tool, arguments: rawArgs } = JSON.parse(json);

  const def = (tools as any)[tool];
  if (!def) {
    throw new Error(`Unknown tool: ${tool}`);
  }

  const args = def.schema.parse(rawArgs); // validate & coerce
  const result = await def.execute(args); // <-- this is the real-world action

  return result;
}

type ToolCall = {
  tool: string;
  arguments: Record<string, unknown>;
};

async function runSingleStepAgent(userInput: string, memory: MemoryStore) {
  // 1. Build context: prior memory + current request
  const context = await memory.retrieveRelevantFacts(userInput);

  const modelResponse = await llm.complete(
    [
      { role: 'system', content: 'You are an assistant that can use tools.' },
      { role: 'system', content: `Tools: ${JSON.stringify(toolDescriptors)}` },
      { role: 'system', content: `Context: ${JSON.stringify(context)}` },
      { role: 'user', content: userInput },
    ],
    { tools: toolDescriptors },
  );

  if (!modelResponse.toolCallJson) {
    // Model chose to answer directly, no external effect
    return { reply: modelResponse.text, effects: [] };
  }

  // 2. Model proposed an action
  const call = JSON.parse(modelResponse.toolCallJson) as ToolCall;

  // 3. Execution layer decides whether and how to run it
  const { allowed, reason } = policy.check(call);
  if (!allowed) {
    return {
      reply: `I cannot perform that action: ${reason}`,
      effects: [],
    };
  }

  const result = await executeTool(call); // <-- real-world effect(s)

  // 4. Feed effect summary back into memory for future steps
  await memory.store({
    type: 'action',
    call,
    resultSummary: summarizeResult(result),
  });

  // 5. Ask model to explain what happened to the user
  const explanation = await llm.complete([
    { role: 'system', content: 'Explain the result of this action to the user.' },
    { role: 'system', content: `Action: ${JSON.stringify(call)}` },
    { role: 'system', content: `Result: ${JSON.stringify(result)}` },
  ]);

  return {
    reply: explanation.text,
    effects: [describeEffects(result)],
  };
}

type EffectCategory = 'read' | 'write' | 'external' | 'irreversible';

interface ToolDefinition<A, R> {
  name: string;
  description: string;
  effect: EffectCategory;
  schema: z.ZodType<A>;
  execute: (args: A) => Promise<R>;
}

const tools: ToolDefinition<any, any>[] = [
  {
    name: 'getUserProfile',
    description: 'Fetch a user profile by ID.',
    effect: 'read',
    schema: z.object({ userId: z.string() }),
    async execute({ userId }) {
      return db.users.findById(userId);
    },
  },
  {
    name: 'updateUserEmail',
    description: 'Update the email address for a user.',
    effect: 'write',
    schema: z.object({ userId: z.string(), newEmail: z.string().email() }),
    async execute({ userId, newEmail }) {
      return db.users.update(userId, { email: newEmail });
    },
  },
  {
    name: 'sendPayment',
    description: 'Send a payment to a recipient.',
    effect: 'irreversible',
    schema: z.object({ toAccount: z.string(), amountCents: z.number().positive() }),
    async execute({ toAccount, amountCents }) {
      return paymentsClient.send({ toAccount, amountCents });
    },
  },
];

async function enforcePolicyAndExecute(
  call: { tool: string; arguments: any },
  ctx: { userId: string },
) {
  const def = tools.find((t) => t.name === call.tool);
  if (!def) throw new Error(`Unknown tool: ${call.tool}`);

  const args = def.schema.parse(call.arguments); // validate first

  switch (def.effect) {
    case 'read':
      // Reads are auto-approved
      return def.execute(args);

    case 'write':
      // Writes may require soft confirmation or extra logging
      await audit.logProposedAction(ctx.userId, def.name, args);
      return def.execute(args);

    case 'external':
    case 'irreversible':
      // High-stakes operations require explicit human approval
      await approvals.request({
        userId: ctx.userId,
        tool: def.name,
        args,
      });
      throw new Error('Action pending approval');

    default:
      throw new Error(`Unhandled effect category: ${(def as any).effect}`);
  }
}

// 1. Model generates code as plain text
const codeResponse = await llm.complete([
  {
    role: 'system',
    content:
      'You are a JavaScript function that receives `input` and must return a JSON-serializable result.',
  },
  { role: 'user', content: 'Given this array of numbers, return only the even ones: [1,2,3,4,5,6]' },
]);

const generatedCode = codeResponse.text; // e.g. "return input.filter(n => n % 2 === 0);"

// 2. Your sandbox decides what this code is allowed to do
const sandbox = new Sandbox({
  // No network, no filesystem, only pure computation
  allowedGlobals: ['input'],
});

// 3. You choose to run it (or not)
async function runGeneratedCode(code: string, input: unknown) {
  const fn = sandbox.compileFunction('input', code);
  return await fn(input); // <-- if this line never runs, no effects occur
}

const result = await runGeneratedCode(generatedCode, [1, 2, 3, 4, 5, 6]);

interface ActionLogEntry {
  id: string;
  timestamp: string;
  sessionId: string;

  // What the user asked
  userRequest: string;

  // What the model proposed
  proposedAction: {
    tool: string;
    arguments: Record<string, unknown>;
    raw: string; // raw toolCallJson or code
  };

  // How policy evaluated it
  authorization: 'automatic' | 'user_confirmed' | 'admin_approved' | 'blocked';
  policyReason: string;

  // What actually happened
  execution: {
    status: 'not_run' | 'success' | 'failure';
    error?: string;
    durationMs?: number;
  };

  // What external effects occurred (if any)
  effects: Array<{
    type: 'read' | 'write' | 'external';
    resource: string;
    reversible: boolean;
  }>;
}

async function logAndExecute(
  call: { tool: string; arguments: any },
  ctx: { userId: string; sessionId: string; userRequest: string },
) {
  const entry: ActionLogEntry = {
    id: crypto.randomUUID(),
    timestamp: new Date().toISOString(),
    sessionId: ctx.sessionId,
    userRequest: ctx.userRequest,
    proposedAction: {
      tool: call.tool,
      arguments: call.arguments,
      raw: JSON.stringify(call),
    },
    authorization: 'automatic',
    policyReason: '',
    execution: { status: 'not_run' },
    effects: [],
  };

  try {
    const { allowed, reason, authorization } = policy.check(call, ctx);
    entry.authorization = authorization;
    entry.policyReason = reason;

    if (!allowed) {
      await actionLog.write(entry);
      throw new Error(`Action blocked: ${reason}`);
    }

    const started = performance.now();
    const result = await enforcePolicyAndExecute(call, ctx);
    const durationMs = performance.now() - started;

    entry.execution = { status: 'success', durationMs };
    entry.effects = describeEffects(result);
    await actionLog.write(entry);

    return result;
  } catch (err: any) {
    entry.execution = { status: 'failure', error: String(err) };
    await actionLog.write(entry);
    throw err;
  }
}