@graphorin/agent 0.6.0 → 0.7.0

package/src/tooling/plan.ts

@@ -0,0 +1,123 @@
+/**
+ * D6 structured plan / todo tool + attention recitation. The tool is a
+ * TodoWrite-style status-flip mutation over the agent's own working
+ * plan, journaled in `RunState.todos` so it survives suspend/resume.
+ * Attention recitation renders the current plan back into the prompt
+ * near the context end each turn (request-only, cache-layout-aware) so
+ * the model keeps its objective in focus on long runs (Manus todo.md /
+ * lost-in-the-middle evidence).
+ *
+ * The tool lives in `@graphorin/agent` (not `@graphorin/tools`) because
+ * it mutates run state: its `execute` writes through a factory-supplied
+ * callback into the active `RunState`.
+ *
+ * @packageDocumentation
+ */
+
+import type { TodoItem, Tool } from '@graphorin/core';
+
+/** Stable name of the built-in plan tool. */
+export const PLAN_TOOL_NAME = 'update_plan';
+
+const STATUS_VALUES = ['pending', 'in_progress', 'completed'] as const;
+
+interface PlanToolInput {
+  readonly todos: ReadonlyArray<{
+    readonly id: string;
+    readonly content: string;
+    readonly status: 'pending' | 'in_progress' | 'completed';
+  }>;
+}
+
+interface PlanToolOutput {
+  readonly count: number;
+  readonly completed: number;
+}
+
+const planInputSchema = {
+  parse: (v: unknown): PlanToolInput => v as PlanToolInput,
+  safeParse: (v: unknown) => {
+    if (typeof v !== 'object' || v === null || !Array.isArray((v as { todos?: unknown }).todos)) {
+      return { success: false as const, error: new Error('expected { todos: TodoItem[] }') };
+    }
+    const todos = (v as { todos: unknown[] }).todos;
+    for (const t of todos) {
+      if (
+        typeof t !== 'object' ||
+        t === null ||
+        typeof (t as { id?: unknown }).id !== 'string' ||
+        typeof (t as { content?: unknown }).content !== 'string' ||
+        !STATUS_VALUES.includes(
+          (t as { status?: unknown }).status as (typeof STATUS_VALUES)[number],
+        )
+      ) {
+        return { success: false as const, error: new Error('invalid TodoItem') };
+      }
+    }
+    return { success: true as const, data: v as PlanToolInput };
+  },
+  toJSON: (): Record<string, unknown> => ({
+    type: 'object',
+    properties: {
+      todos: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            content: { type: 'string' },
+            status: { type: 'string', enum: [...STATUS_VALUES] },
+          },
+          required: ['id', 'content', 'status'],
+        },
+      },
+    },
+    required: ['todos'],
+  }),
+} as unknown as Tool<PlanToolInput, PlanToolOutput>['inputSchema'];
+
+/**
+ * Build the plan tool. `applyTodos` writes the validated list into the
+ * active RunState (the factory closes over `activeRunState`). Pure
+ * read-only-ish: it mutates run bookkeeping, not the outside world, so
+ * it is `sideEffectClass: 'read-only'` (never a data-flow sink).
+ */
+export function createPlanTool(
+  applyTodos: (todos: ReadonlyArray<TodoItem>) => void,
+): Tool<PlanToolInput, PlanToolOutput> {
+  return {
+    name: PLAN_TOOL_NAME,
+    description:
+      'Record or update your working plan as a checklist of todos (TodoWrite-style, full replace). Each item has an id, content, and status (pending | in_progress | completed). Keep exactly ONE item in_progress at a time; mark items completed as you finish them. The plan is journaled and recited back to you each turn - use it to stay on task across a long run.',
+    inputSchema: planInputSchema,
+    sideEffectClass: 'read-only',
+    async execute(input): Promise<PlanToolOutput> {
+      const todos: TodoItem[] = input.todos.map((t) => ({
+        id: t.id,
+        content: t.content,
+        status: t.status,
+      }));
+      applyTodos(todos);
+      return {
+        count: todos.length,
+        completed: todos.filter((t) => t.status === 'completed').length,
+      };
+    },
+  } as Tool<PlanToolInput, PlanToolOutput>;
+}
+
+/**
+ * Render the attention-recitation block for the current plan. Returns
+ * `null` for an empty plan (nothing to recite). The block is appended to
+ * the per-step request copy near the END so it rides the last
+ * cache anchor and never busts the stable prompt prefix.
+ *
+ * @stable
+ */
+export function renderPlanRecitation(todos: ReadonlyArray<TodoItem> | undefined): string | null {
+  if (todos === undefined || todos.length === 0) return null;
+  const mark = (s: TodoItem['status']): string =>
+    s === 'completed' ? '[x]' : s === 'in_progress' ? '[~]' : '[ ]';
+  const lines = todos.map((t) => `${mark(t.status)} ${t.content}`);
+  return `<plan reminder="stay on task; keep one item in progress">\n${lines.join('\n')}\n</plan>`;
+}

package/src/tooling/policy.ts

@@ -0,0 +1,67 @@
+/**
+ * Agent-side adapter for the D4 tool-argument policy (Progent) and the
+ * Rule-of-Two capability preset. Compiles `AgentConfig.toolPolicy` /
+ * `AgentConfig.ruleOfTwo` into the structural
+ * {@link ToolArgumentPolicyGuard} the tool executor consumes plus a
+ * capability floor the run loop folds into its single-writer gate.
+ *
+ * The pure decision engine lives in `@graphorin/security/policy`; this
+ * module is the thin binding, mirroring `tooling/dataflow.ts`.
+ *
+ * @packageDocumentation
+ */
+
+import { isUntrustedTrustClass } from '@graphorin/security/dataflow';
+import {
+  buildRuleOfTwoPolicy,
+  evaluateToolArgumentPolicy,
+  type PolicySideEffectClass,
+  type RuleOfTwoProfile,
+  type ToolArgumentPolicy,
+} from '@graphorin/security/policy';
+import type { ToolArgumentPolicyGuard } from '@graphorin/tools/executor';
+
+export type { RuleOfTwoProfile, ToolArgumentPolicy } from '@graphorin/security/policy';
+
+/**
+ * Compile the agent's opt-in tool-argument policy + Rule-of-Two profile
+ * into a single guard. `ruleOfTwo` is compiled first (yielding a base
+ * policy + optional read-only floor); an explicit `toolPolicy` is
+ * appended so its rules compose - a forbid in either always wins
+ * (forbid-before-allow). Returns `{ guard: undefined }` when neither is
+ * configured (zero overhead on the default path).
+ */
+export function buildToolArgumentPolicy(
+  toolPolicy: ToolArgumentPolicy | undefined,
+  ruleOfTwo: RuleOfTwoProfile | undefined,
+): { readonly guard: ToolArgumentPolicyGuard | undefined; readonly capabilityFloor?: 'read-only' } {
+  if (toolPolicy === undefined && ruleOfTwo === undefined) {
+    return { guard: undefined };
+  }
+
+  const compiled = ruleOfTwo !== undefined ? buildRuleOfTwoPolicy(ruleOfTwo) : undefined;
+  const merged: ToolArgumentPolicy = {
+    rules: [...(compiled?.policy.rules ?? []), ...(toolPolicy?.rules ?? [])],
+    defaultDenySensitive:
+      (compiled?.policy.defaultDenySensitive ?? false) ||
+      (toolPolicy?.defaultDenySensitive ?? false),
+  };
+
+  const guard: ToolArgumentPolicyGuard = {
+    evaluate: (input) =>
+      evaluateToolArgumentPolicy(merged, {
+        toolName: input.toolName,
+        sideEffectClass: input.sideEffectClass as PolicySideEffectClass,
+        sensitive: input.sensitive,
+        // W-101: derived with the same taxonomy the taint engine uses,
+        // so the Rule-of-Two untrustedInput leg and dataflow policy can
+        // never disagree about what "untrusted source" means.
+        untrustedSource: isUntrustedTrustClass(input.trustClass),
+        args: input.args,
+      }),
+  };
+
+  return compiled?.capability !== undefined
+    ? { guard, capabilityFloor: compiled.capability }
+    : { guard };
+}

package/src/tooling/registry-build.ts

@@ -0,0 +1,191 @@
+/**
+ * Assemble a single `@graphorin/tools` {@link ToolRegistry} from every
+ * tool source the agent knows about (first-party `config.tools` + skill
+ * tools), then resolve cross-source name collisions deterministically.
+ *
+ * This realises Principle #12 (one registry, one collision policy) and
+ * gives `createToolRegistry(...)` its first production call-site
+ * (`createAgent(...)` warm-up - see `factory.ts`). The run loop consumes
+ * the resulting registry in a later work item (WI-03); `tool_search`
+ * uses it in WI-05. This module only *builds* it.
+ *
+ * Two deliberate fidelity notes (verified against source, not the plan):
+ *  - **MCP tools are not auto-stamped.** `adaptMCPTools(...)` returns
+ *    plain `Tool`s; `__source`/`__trustClass` are only ever assigned by
+ *    the registry's `normaliseTool(...)` at registration time, derived
+ *    from the `source` passed to `register(...)`. So {@link inferToolSource}
+ *    honours an explicit `__source` stamp if one is present (forward-
+ *    compatible with a dedicated `mcp` config hook / re-registered
+ *    `ResolvedTool`s) and otherwise treats the tool as first-party. The
+ *    MCP tool's baked-in `sandboxPolicy` / `inboundSanitization` are
+ *    preserved regardless (operator override > trust-class default).
+ *  - **Skill tool-stamping lives here, not in `@graphorin/skills`.** The
+ *    skills loader defers it (it does not depend on a tools registry);
+ *    the agent - which depends on both - stamps each inline skill tool
+ *    via `stampSkillTool(...)`.
+ *
+ * @packageDocumentation
+ */
+
+import type { Tool, ToolSource } from '@graphorin/core';
+import type { SkillMetadata } from '@graphorin/skills';
+import { stampSkillTool } from '@graphorin/skills';
+import {
+  type CollisionContext,
+  type CollisionResolution,
+  type CollisionStrategy,
+  createToolRegistry,
+  type ToolAuditEvent,
+  type ToolRegistry,
+  type ToolSearchEmbedder,
+} from '@graphorin/tools/registry';
+
+import type { SkillsRegistryLike } from '../types.js';
+
+/** The source attributed to an unstamped first-party `config.tools` entry. */
+const FIRST_PARTY_SOURCE: ToolSource = Object.freeze({ kind: 'first-party' });
+
+/** The five `ToolSource.kind` discriminants (used to validate a stamp). */
+const TOOL_SOURCE_KINDS: ReadonlySet<string> = new Set([
+  'first-party',
+  'built-in',
+  'skill',
+  'mcp',
+  'web-search',
+]);
+
+/** Options for {@link buildToolRegistry}. */
+export interface BuildToolRegistryOptions {
+  /** First-party (and any pre-stamped) tools, i.e. `config.tools`. */
+  readonly tools?: ReadonlyArray<Tool<unknown, unknown, unknown>>;
+  /**
+   * The agent's skill registry (`config.skills`). Only entries that
+   * structurally match the {@link SkillLike} surface contribute tools;
+   * non-inline skill sources expose `tools(): []` and are a no-op here.
+   */
+  readonly skills?: SkillsRegistryLike;
+  /** Collision-resolution strategy. Default `'auto-prefix'`. */
+  readonly collisionStrategy?: CollisionStrategy;
+  /**
+   * Context tag carried on the collision audit rows + used for the
+   * `'priority'` tie-break boost. Default `{ source: first-party }`.
+   */
+  readonly collisionContext?: CollisionContext;
+  /** Audit sink forwarded to the registry (collision + classification rows). */
+  readonly emitAudit?: (event: ToolAuditEvent) => void;
+  /** Semantic-search embedder. Passed through; consumed by `tool_search` (WI-05). */
+  readonly embedder?: ToolSearchEmbedder;
+  /** Cosine threshold for the semantic search stage (WI-05). */
+  readonly semanticScoreThreshold?: number;
+}
+
+/** Outcome of {@link buildToolRegistry}. */
+export interface BuildToolRegistryResult {
+  /** The assembled registry, post collision-resolution. */
+  readonly registry: ToolRegistry;
+  /** The collision resolutions (also emitted on the audit sink). */
+  readonly resolutions: ReadonlyArray<CollisionResolution>;
+  /** Count of tools registered across every source. */
+  readonly registered: number;
+  /** Count of `skills.list()` entries skipped for not matching the `Skill` surface. */
+  readonly skippedSkillEntries: number;
+}
+
+/**
+ * Build and collision-resolve a {@link ToolRegistry} from the supplied
+ * tool sources.
+ *
+ * Registration order (which seeds the `'registration-order'` tie-break)
+ * is: every `tools` entry, then every inline tool of every skill.
+ * Throws whatever `register(...)` throws for a malformed tool
+ * (`InvalidExampleError`, `InvalidPreferredModelError`,
+ * `InvalidSideEffectClassError`) - the registry is the validation
+ * authority, so a bad tool fails fast at build time.
+ *
+ * @stable
+ */
+export function buildToolRegistry(options: BuildToolRegistryOptions = {}): BuildToolRegistryResult {
+  const registry = createToolRegistry({
+    ...(options.emitAudit !== undefined ? { emitAudit: options.emitAudit } : {}),
+    ...(options.embedder !== undefined ? { embedder: options.embedder } : {}),
+    ...(options.semanticScoreThreshold !== undefined
+      ? { semanticScoreThreshold: options.semanticScoreThreshold }
+      : {}),
+  });
+
+  let registered = 0;
+
+  // 1. First-party / pre-stamped tools (`config.tools`).
+  for (const tool of options.tools ?? []) {
+    registry.register(tool, inferToolSource(tool));
+    registered += 1;
+  }
+
+  // 2. Skill tools. The agent accepts a loose `SkillsRegistryLike`, so
+  //    each `list()` entry is narrowed structurally before stamping.
+  let skippedSkillEntries = 0;
+  for (const entry of options.skills?.list?.() ?? []) {
+    if (!isSkillLike(entry)) {
+      skippedSkillEntries += 1;
+      continue;
+    }
+    for (const tool of entry.tools()) {
+      const stamped = stampSkillTool(tool, entry);
+      registry.register(stamped.tool, stamped.source);
+      registered += 1;
+    }
+  }
+
+  // 3. Resolve collisions deterministically (first-party wins; losers
+  //    are namespaced). `assertNoDuplicates(strategy, ctx)` emits a
+  //    `tool:collision:*` audit row per resolution.
+  const resolutions = registry.assertNoDuplicates(
+    options.collisionStrategy ?? 'auto-prefix',
+    options.collisionContext ?? { source: FIRST_PARTY_SOURCE },
+  );
+
+  return Object.freeze({ registry, resolutions, registered, skippedSkillEntries });
+}
+
+/**
+ * Derive the {@link ToolSource} for a `config.tools` entry. Honours an
+ * explicit, well-formed `__source` stamp when present (so re-registered
+ * `ResolvedTool`s and a future `mcp` config hook keep their provenance);
+ * otherwise the tool is first-party. See the module doc on why MCP tools
+ * are *not* auto-detected here.
+ */
+function inferToolSource(tool: Tool<unknown, unknown, unknown>): ToolSource {
+  const stamped = (tool as { readonly __source?: unknown }).__source;
+  return isToolSource(stamped) ? stamped : FIRST_PARTY_SOURCE;
+}
+
+/** Structural guard: a well-formed {@link ToolSource} discriminated union. */
+function isToolSource(value: unknown): value is ToolSource {
+  if (typeof value !== 'object' || value === null) return false;
+  const kind = (value as { readonly kind?: unknown }).kind;
+  return typeof kind === 'string' && TOOL_SOURCE_KINDS.has(kind);
+}
+
+/**
+ * Minimal structural view of a `@graphorin/skills` `Skill` - exactly the
+ * members {@link buildToolRegistry} reads. The agent's `SkillsRegistryLike`
+ * is intentionally loose (`list?(): unknown[]`), so entries are validated
+ * at runtime before being treated as skills.
+ */
+interface SkillLike {
+  readonly metadata: SkillMetadata;
+  tools(): ReadonlyArray<Tool<unknown, unknown, unknown>>;
+}
+
+/** Structural guard for the {@link SkillLike} surface. */
+function isSkillLike(value: unknown): value is SkillLike {
+  if (typeof value !== 'object' || value === null) return false;
+  const metadata = (value as { readonly metadata?: unknown }).metadata;
+  const metadataOk =
+    typeof metadata === 'object' &&
+    metadata !== null &&
+    typeof (metadata as { readonly name?: unknown }).name === 'string' &&
+    typeof (metadata as { readonly graphorinTrustLevel?: unknown }).graphorinTrustLevel ===
+      'string';
+  return metadataOk && typeof (value as { readonly tools?: unknown }).tools === 'function';
+}