// The brain: history in, next action out. Nothing else.
type Policy = (history: Entry[]) => Promise<{ action: Action }>;

type Action =
  | { kind: "final"; text: string }
  | { kind: "tools"; calls: ToolCall[] };

export async function runAgent(
  question: string,
  policy: Policy,
  registry: Registry,
  ctx: ToolContext,
  { maxSteps = 8 } = {},
) {
  const history: Entry[] = [{ role: "question", text: question }];

  for (let step = 1; step <= maxSteps; step++) {
    const { action } = await policy(history);

    // The model says it is finished. Believe it, and stop.
    if (action.kind === "final") return { answer: action.text, step };

    // Independent calls go together, not one after another.
    const results = await Promise.all(
      action.calls.map((c) => registry.call(c.name, c.args, ctx)),
    );

    for (const r of results)
      history.push({ role: "observation", text: r.observation });
  }

  // The step cap. Without this line you have a bill, not a feature.
  return { answer: "stopped: hit the step cap", step: maxSteps };
}

import { z } from "zod";

const issueRefund = defineTool({
  // 1 · snake_case, short, unmistakable. The model types this.
  name: "issue_refund",

  // 2 · this IS prompt text. It is how the model chooses.
  description:
    "Refund one order in full. Only works inside the refund " +
    "policy. Money leaves the account, so use it once.",

  // 3 · the contract. Narrow types here are narrow privileges later.
  schema: z.object({
    orderId: z.string().min(3),
    reason:  z.enum(["damaged", "late", "wrong_item"]),
  }),

  // 4 · what it does to the world: read | write | irreversible
  effect: "irreversible",

  async run({ orderId, reason }, ctx) {
    const order = await findOrder(orderId);

    // ctx comes from YOUR code, never from the model's arguments.
    if (!order || order.tenantId !== ctx.tenantId)
      return `refused: no order ${orderId} on this account`;

    // The rule is re-checked HERE. The model only asked.
    if (order.totalGbp > MAX_AUTO_REFUND)
      return `refused: over the GBP ${MAX_AUTO_REFUND} limit`;

    return await refund(order, reason);
  },
});

// GOOD: narrow, typed, and the server re-checks everything
{
  name: "refund_order",
  input: {
    orderId: "string",
    reason:  "enum[damaged, late, wrong_item]"
  }
}
// server re-checks: caller owns this order,
//                   amount is under the cap,
//                   it was not already refunded.
// Worst case if the model is wrong or steered:
//   ONE wrong refund, under the cap, fully logged.


// DANGEROUS: unbounded, and the model picks how far it reaches
{
  name: "run_sql",
  input: { query: "string" }
}
// Worst case: every row of every table, read or deleted.

// Same family of mistake:
{ name: "http_get",  input: { url: "string" } }   // your whole VPC
{ name: "shell",     input: { cmd: "string" } }   // game over
{ name: "send_email",input: { to: "string", body: "string" } }

// Every failure comes back as an OBSERVATION the model can read.
async call(name, rawArgs, ctx): Promise<ToolResult> {
  const tool = byName.get(name);

  // 1 · invented a tool. Say so, and say what exists.
  if (!tool) return {
    ok: false, retryable: true,
    observation: `error: no tool named "${name}". ` +
                 `Available tools: ${names.join(", ")}.`,
  };

  // 2 · bad arguments. Name the field and the reason.
  const parsed = tool.parse(rawArgs);
  if (!parsed.ok) return {
    ok: false, retryable: true,
    observation: `error: invalid arguments for ${name}. ` +
                 parsed.message,  // "reason: expected damaged|late"
  };

  // 3 · the dependency fell over. Still an observation.
  try {
    const raw = await tool.invoke(parsed.args, ctx);
    return { ok: true, ...bound(raw, tool.maxChars) };
  } catch (err) {
    return {
      ok: false, retryable: true,
      observation: `error: ${name} failed. ${message(err)}`,
    };
  }
}

export function choosePlanner(shape: TaskShape): PlannerChoice {
  // Cheapest answer first, and it wins ties.
  if (shape.pathKnown && !shape.stepsDependOnResults) {
    return { kind: "none",
      because: "the path is known, so a workflow is cheaper and testable" };
  }

  if (shape.qualityOverCost && !shape.stepsDependOnResults) {
    return { kind: "reflect",
      because: "one artifact where quality is worth extra calls" };
  }

  if (shape.pathKnown) {
    return { kind: "plan_then_execute",
      because: "predictable shape, so plan once and validate each step" };
  }

  return { kind: "react",
    because: "the next step is only knowable after the last observation" };
}

// $ npm run lab .../s07-agent-architecture/decide.ts
//
// 1 · planning    react
//    because      the next step is only knowable after the last
//    breaks as    wandering, and error compounding
//    guardrail    step cap, budget, repeat detection, validation

// Bare chain: every step trusts the one before it.
export function chainSuccess(perStep: number, steps: number) {
  return perStep ** steps;
}

// With a check between steps. `catchRate` is the share of bad
// steps your validation actually catches and retries.
export function chainSuccessWithChecks(
  perStep: number, steps: number, catchRate: number,
) {
  const effective = perStep + (1 - perStep) * catchRate;
  return chainSuccess(Math.min(effective, 1), steps);
}

// 90% per step, 10 steps:
chainSuccess(0.9, 10);                 // 0.349  ouch
chainSuccessWithChecks(0.9, 10, 0.8);  // 0.817  same model

// And the number that sets your step cap:
maxStepsFor(0.95, 0.9);   // 2 steps before you drop under 90%
maxStepsFor(0.99, 0.9);   // 10
maxStepsFor(0.999, 0.9);  // 105

export async function runDurable(runId, steps, store, perform) {
  // Load, or start fresh. `completed.length` IS the resume point.
  const record = (await store.load(runId)) ?? {
    runId, status: "running", completed: [], approvedSteps: [],
  };

  for (let i = record.completed.length; i < steps.length; i++) {
    const step = steps[i];

    // Waiting on a human is a STATE, not a held-open socket.
    if (needsApproval(step) &&
        !record.approvedSteps.includes(step.name)) {
      record.status  = "awaiting_approval";
      record.pending = { name: step.name, effect: step.effect };
      await store.save(record);
      return record;              // come back tomorrow, different process
    }

    const output = await perform(step, record.completed);
    record.completed.push({ name: step.name, output, effect: step.effect });

    // AFTER every step. Not every five. Not at the end.
    await store.save(record);
  }

  record.status = "done";
  await store.save(record);
  return record;
}

// Divide, do not share. A shared pot is a first-come budget.
const perWorker = (budgetUsd - coordinationUsd) / subtasks.length;

const results = await Promise.all(subtasks.map(async (task) => {
  // A FRESH history per worker. This is the point of the pattern.
  const isolated = [`goal: ${task.goal}`];
  try {
    const { output, costUsd } = await worker(task, isolated);
    if (costUsd > perWorker)
      return { id: task.id, output, trusted: false, costUsd,
               note: "over its share" };
    return { id: task.id, output, trusted: true, costUsd };
  } catch (err) {
    // Named, not silently dropped from the merge.
    return { id: task.id, output: "", trusted: false,
             costUsd: 0, note: message(err) };
  }
}));

const merged   = merge(results.filter((r) => r.trusted));
const excluded = results.filter((r) => !r.trusted).map((r) => r.id);

// The number that ends the argument:
coordinationShare(result);  // 0.5 = half the bill was talking