chore(examples): use built-in framework surface — hooks-and-scripts, host-test, mcp-app, skills-starter (#471)

* chore(examples/host-test): record request.lineage through the public context member

request.lineage is a first-class Observed<AgentLineage> on AgentRequestContext
since #444, so the probe reads it directly instead of casting for an optional
member and records it on every line (available or unavailable with reason).
renderLineage types the serialized value against the public AgentLineage and
Observed types. The route-unit suite asserts a mounted lineage is recorded and
rendered.

* chore(examples/skills-starter): type outcome graders against agent-bundle/eval

Both graders declare themselves as the public EvalGraderFunction instead of
restating the grader context and outcome shapes by hand. The README names the
build output directory the CLI actually writes (artifact/, not dist/).

* chore(examples/mcp-app): type the outcome grader against agent-bundle/eval

The status grader declares itself as the public EvalGraderFunction instead of
restating the grader context and outcome shapes. The README's mcp run example
reuses the build output the CLI actually writes (--artifact artifact).

Author: ScriptedAlchemy

examples/host-test/README.md

@@ -3,7 +3,7 @@
 A probing plugin. Install it into a Claude Code, Codex, or Cursor home, drive
 one agent session, and read back exactly what that host sent to every plugin
 hook and MCP call — the raw envelope, the framework request context each
-handler saw, and (once the framework resolves it) the conversation lineage.
+handler saw, and the conversation lineage the runtime resolved for it.
 It is the acceptance vehicle for `request.lineage` and the evidence source for
 `docs/audits/*-host-lineage-matrix.md`.
 
@@ -25,7 +25,7 @@ bounded summary into the durable state kernel (`src/state.ts`,
 | --- | --- |
 | `event.native` | The complete host payload, byte for byte, with secret-looking values replaced by `[redacted]`. |
 | `event.canonical` | The framework's canonical identity (`event`, `idempotencyKey`, `observedAt`, `provenance`). |
-| `request` | `(await agent())` as the route saw it: `invocation`, `host`, `session`, `actor`, `workspace`, `capabilities`, provider keys, whether state and notices were mounted, and `lineage` when the runtime supplies it. |
+| `request` | `(await agent())` as the route saw it: `invocation`, `host`, `session`, `actor`, `workspace`, `capabilities`, `lineage`, provider keys, and whether state and notices were mounted. `lineage` is always present: `available` with the resolved tree position, or `unavailable` with the runtime's per-host reason. |
 | `ids` | Every identity-shaped native field (`conversation_id`, `generation_id`, `session_id`, `subagent_id`, `tool_call_id`, `agent_id`, `turn_id`, `user_email`, …) lifted out for filtering. |
 | `process` | `pid`, `ppid`, `cwd`, `execPath`, entry file, uptime — of the process that ran the route. |
 | `runtime` | `shared-runtime` when the hook reached the warm MCP-hosted runtime, `standalone-hook` when it fell back to the hook process, `mcp-server`, or `cli`. |

examples/host-test/src/capture.ts

@@ -135,25 +135,27 @@ const detectRuntime = (context: AgentRequestContext, argv: readonly string[]): C
   }
 };
 
-/** The framework request context as the route observed it, minus non-data members. */
-export const snapshotRequest = (context: AgentRequestContext): JsonObject => {
-  const lineage = (context as AgentRequestContext & { readonly lineage?: unknown }).lineage;
-  return {
-    actor: asJson(context.actor),
-    capabilities: asJson(context.capabilities),
-    hasNotices: context.notices !== undefined,
-    hasState: context.state !== undefined,
-    host: asJson(context.host),
-    invocation: asJson(context.invocation),
-    ...(lineage === undefined ? {} : { lineage: asJson(lineage) }),
-    providers: {
-      keys: Object.keys(context.providers).sort((left, right) => left.localeCompare(right)),
-      processLifetime: asJson(context.providers.processLifetime),
-    },
-    session: asJson(context.session),
-    workspace: asJson(context.workspace),
-  };
-};
+/**
+ * The framework request context as the route observed it, minus non-data
+ * members. `lineage` is a first-class `Observed` member of the context, so it
+ * is recorded on every line: `available` with the resolved tree position, or
+ * `unavailable` with the runtime's per-host reason.
+ */
+export const snapshotRequest = (context: AgentRequestContext): JsonObject => ({
+  actor: asJson(context.actor),
+  capabilities: asJson(context.capabilities),
+  hasNotices: context.notices !== undefined,
+  hasState: context.state !== undefined,
+  host: asJson(context.host),
+  invocation: asJson(context.invocation),
+  lineage: asJson(context.lineage),
+  providers: {
+    keys: Object.keys(context.providers).sort((left, right) => left.localeCompare(right)),
+    processLifetime: asJson(context.providers.processLifetime),
+  },
+  session: asJson(context.session),
+  workspace: asJson(context.workspace),
+});
 
 export interface CaptureInput {
   readonly event?: AgentEventRouteProps;

examples/host-test/src/dump.ts

@@ -1,8 +1,10 @@
 import {
   agent,
+  type AgentLineage,
   type AgentStateHandle,
   type JsonObject,
   type JsonValue,
+  type Observed,
 } from '@agent-bundle/runtime';
 import { z } from 'zod';
 
@@ -155,9 +157,11 @@ export const renderDumpMarkdown = (result: DumpResult): string => {
 /** One cell: `depth N · <conversation> ← <parent> (resolution)` or the typed unavailable reason. */
 export const renderLineage = (lineage: JsonValue | undefined): string => {
   if (lineage === undefined || lineage === null || typeof lineage !== 'object' || Array.isArray(lineage)) return 'not recorded';
-  const observed = lineage as { readonly state?: string; readonly reason?: string; readonly value?: JsonValue };
-  if (observed.state !== 'available') return `unavailable · ${observed.reason ?? 'unknown'}`;
-  const value = (observed.value ?? {}) as { readonly conversation?: string; readonly depth?: number; readonly parent?: string; readonly resolution?: string; readonly root?: string };
-  const parent = value.parent === undefined ? '' : ` ← ${value.parent}`;
-  return `depth ${String(value.depth ?? '?')} · ${value.conversation ?? '?'}${parent} (${value.resolution ?? '?'})`;
+  // The serialized `Observed<AgentLineage>` the capture wrote from `request.lineage`.
+  const observed = lineage as unknown as Observed<AgentLineage> | { readonly state?: undefined };
+  if (observed.state !== 'available') {
+    return `unavailable · ${observed.state === 'unavailable' ? observed.reason : 'unknown'}`;
+  }
+  const { conversation, depth, parent, resolution } = observed.value;
+  return `depth ${String(depth)} · ${conversation}${parent === undefined ? '' : ` ← ${parent}`} (${resolution})`;
 };

examples/host-test/tests/route-unit/routes.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import { afterEach, beforeEach, expect, it } from '@rstest/core';
-import { available } from '@agent-bundle/runtime';
+import { available, type AgentLineage } from '@agent-bundle/runtime';
 import {
   createGeneratedRuntimeState,
   type GeneratedRuntimeState,
@@ -46,12 +46,19 @@ const eventInput = (
   native,
 });
 
-const render = async (route: string, input: unknown, sessionId = 'root-session', host = 'claude') => {
+const render = async (
+  route: string,
+  input: unknown,
+  sessionId = 'root-session',
+  host = 'claude',
+  lineage?: AgentLineage,
+) => {
   const bindings = await runtimeState.requestBindings();
   try {
     return await renderRoute(route, {
       context: {
         host: available({ name: host }, 'native'),
+        ...(lineage === undefined ? {} : { lineage: available(lineage, 'native') }),
         noticeLedger: bindings.noticeLedger,
         session: available({ sessionId }, 'native'),
         state: bindings.state,
@@ -125,6 +132,9 @@ it('records the complete native envelope, the request context, and env names for
       hasState: true,
       host: { state: 'available', value: { name: 'claude' } },
       invocation: { kind: 'event' },
+      // `request.lineage` is recorded on every line; the route-unit context
+      // mounts none, so the runtime's unavailable reason is the evidence.
+      lineage: { state: 'unavailable' },
       session: { state: 'available', value: { sessionId: 'root-session' } },
     },
   });
@@ -133,6 +143,36 @@ it('records the complete native envelope, the request context, and env names for
   expect(JSON.stringify(record)).not.toContain(logDir.replace('captures.ndjson', 'value-should-not-appear'));
 });
 
+it('records the mounted request.lineage verbatim and renders it in the dump table', async () => {
+  const lineage: AgentLineage = {
+    conversation: 'agent-1',
+    depth: 1,
+    parent: 'root-session',
+    resolution: 'registry',
+    root: 'root-session',
+    subagent: { id: 'agent-1' },
+  };
+  await render('event:tool/before', eventInput('tool/before', {
+    agent_id: 'agent-1',
+    cwd: '/repo',
+    hook_event_name: 'PreToolUse',
+    session_id: 'root-session',
+    tool_input: { command: 'pwd' },
+    tool_name: 'Bash',
+    tool_use_id: 'toolu_02',
+  }), 'root-session', 'claude', lineage);
+
+  const [record] = await readLogLines();
+  expect(record).toMatchObject({ request: { lineage: { source: 'native', state: 'available', value: lineage } } });
+
+  const dumped = await render('tool:host-test/dump', { conversation: 'agent-1' });
+  expect(dumped.document.value).toMatchObject({
+    matched: 1,
+    records: [expect.objectContaining({ lineage: { source: 'native', state: 'available', value: lineage } })],
+  });
+  expectDocument(dumped).toContainMarkdown('depth 1 · agent-1 ← root-session (registry)');
+});
+
 it('redacts secret-looking native values but keeps ids intact', async () => {
   await render('event:tool/before', eventInput('tool/before', {
     cwd: '/repo',

examples/mcp-app/README.md

@@ -84,7 +84,7 @@ pnpm exec agent-bundle mcp run --server status --target portable
 ```
 
 The command resolves the generated entry from the portable target's MCP
-manifest, building a temporary artifact first; pass `--artifact dist` to
+manifest, building a temporary artifact first; pass `--artifact artifact` to
 reuse the `pnpm build` output instead. Closing stdin exits 0 and Ctrl-C
 exits 130, and per-server state persists under
 `.agent-bundle/mcp-run/portable/status`.

examples/mcp-app/evals/graders/status-result.ts

@@ -1,11 +1,15 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
+import type { EvalGraderFunction } from 'agent-bundle/eval';
+
 import { isHealthyCompilerFixture } from '../../src/compiler-status-contract.ts';
 
-export default async ({ fixturePath }: { readonly fixturePath: string }) => {
+const grade: EvalGraderFunction = async ({ fixturePath }) => {
   const result = JSON.parse(await readFile(join(fixturePath, 'result.json'), 'utf8')) as unknown;
   return isHealthyCompilerFixture(result)
-    ? { detail: 'The compiler service is healthy.', outcome: 'pass' as const }
-    : { detail: 'The compiler service did not report a healthy status.', outcome: 'fail' as const };
+    ? { detail: 'The compiler service is healthy.', outcome: 'pass' }
+    : { detail: 'The compiler service did not report a healthy status.', outcome: 'fail' };
 };
+
+export default grade;

examples/skills-starter/README.md

@@ -64,6 +64,6 @@ pnpm dev
 
 Use `pnpm check` when you want validation and a build without starting the
 Workbench; run the deterministic eval command separately when you need the
-release-readiness verdict. Generated output is written to `dist/`; its root
-contract is `dist/agent-bundle.manifest.json`. The `.agent-bundle/` directory
+release-readiness verdict. Generated output is written to `artifact/`; its root
+contract is `artifact/agent-bundle.manifest.json`. The `.agent-bundle/` directory
 contains development state and is not source material.

examples/skills-starter/evals/graders/operations-result.ts

@@ -1,18 +1,24 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
-export default async ({ fixturePath }: { readonly fixturePath: string }) => {
-  const result = JSON.parse(await readFile(join(fixturePath, 'result.json'), 'utf8')) as {
-    readonly evidence?: unknown;
-    readonly outcome?: string;
-    readonly rollbackOrStopCondition?: string;
-  };
+import type { EvalGraderFunction } from 'agent-bundle/eval';
+
+interface OperationsResult {
+  readonly evidence?: unknown;
+  readonly outcome?: string;
+  readonly rollbackOrStopCondition?: string;
+}
+
+const grade: EvalGraderFunction = async ({ fixturePath }) => {
+  const result = JSON.parse(await readFile(join(fixturePath, 'result.json'), 'utf8')) as OperationsResult;
   const complete = result.outcome === 'ready'
     && Array.isArray(result.evidence)
     && result.evidence.length >= 2
     && typeof result.rollbackOrStopCondition === 'string'
     && result.rollbackOrStopCondition.length > 0;
   return complete
-    ? { detail: 'The operational handoff includes evidence and a rollback or stop condition.', outcome: 'pass' as const }
-    : { detail: 'The operational handoff is missing evidence or a rollback or stop condition.', outcome: 'fail' as const };
+    ? { detail: 'The operational handoff includes evidence and a rollback or stop condition.', outcome: 'pass' }
+    : { detail: 'The operational handoff is missing evidence or a rollback or stop condition.', outcome: 'fail' };
 };
+
+export default grade;

examples/skills-starter/evals/graders/release-result.ts

@@ -1,12 +1,18 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
-export default async ({ fixturePath }: { readonly fixturePath: string }) => {
-  const result = JSON.parse(await readFile(join(fixturePath, 'result.json'), 'utf8')) as {
-    readonly blockers?: unknown;
-    readonly verdict?: string;
-  };
+import type { EvalGraderFunction } from 'agent-bundle/eval';
+
+interface ReleaseResult {
+  readonly blockers?: unknown;
+  readonly verdict?: string;
+}
+
+const grade: EvalGraderFunction = async ({ fixturePath }) => {
+  const result = JSON.parse(await readFile(join(fixturePath, 'result.json'), 'utf8')) as ReleaseResult;
   return result.verdict === 'ready' && Array.isArray(result.blockers) && result.blockers.length === 0
-    ? { detail: 'The release artifact is ready with no blockers.', outcome: 'pass' as const }
-    : { detail: 'The release artifact is not ready or has unresolved blockers.', outcome: 'fail' as const };
+    ? { detail: 'The release artifact is ready with no blockers.', outcome: 'pass' }
+    : { detail: 'The release artifact is not ready or has unresolved blockers.', outcome: 'fail' };
 };
+
+export default grade;