@warpgogol/werkstatt-shared 0.14.1 → 0.16.0

package/src/{share/agent → agent}/api-catalog.ts

@@ -13,6 +13,8 @@ No I/O — the kernel command loads the manifest and passes it here.
 <CHANGE_SUMMARY>
   <item>RFC-0783: initial API Catalog linkset+json projection.</item>
   <item>RFC-0954: add search endpoint link when interfaces.search is non-null.</item>
+  <item>RFC-1114: link agent-card.json (service-desc) + a2a endpoint (service) when interfaces.a2a is non-null.</item>
+  <item>RFC-1114: minimal real A2A endpoint + honest agent card</item>
 </CHANGE_SUMMARY>
 */
 
@@ -63,13 +65,24 @@ export function buildApiCatalog(manifest: AgentSurfaceManifest): ApiCatalog {
   if (manifest.interfaces.mcp) {
     serviceDesc.push({ href: "/.well-known/mcp/server-card.json", type: "application/json" });
   }
+  if (manifest.interfaces.a2a) {
+    serviceDesc.push({ href: "/.well-known/agent-card.json", type: "application/json" });
+  }
   if (serviceDesc.length > 0) {
     serviceDesc.sort((a, b) => a.href.localeCompare(b.href));
     entry["service-desc"] = serviceDesc;
   }
 
+  const service: ApiCatalogLink[] = [];
   if (manifest.interfaces.mcp) {
-    entry["service"] = [{ href: manifest.interfaces.mcp.url, type: "application/json" }];
+    service.push({ href: manifest.interfaces.mcp.url, type: "application/json" });
+  }
+  if (manifest.interfaces.a2a) {
+    service.push({ href: manifest.interfaces.a2a.url, type: "application/json" });
+  }
+  if (service.length > 0) {
+    service.sort((a, b) => a.href.localeCompare(b.href));
+    entry["service"] = service;
   }
 
   if (manifest.interfaces.search) {

package/src/{share/agent → agent}/ard-catalog.ts

@@ -12,7 +12,12 @@ passes it here.
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Initial ARD ai-catalog.json projection for isitagentready.com ARD check.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/{share/agent → agent}/dns-aid.test.ts

@@ -11,8 +11,8 @@ Verifies determinism, domain extraction, and content URL construction.
 */
 
 import { describe, it, expect } from "vitest";
-import { buildDnsAidRecord } from "@warpgogol/werkstatt-shared/share/agent";
-import type { AgentSurfaceManifest } from "@warpgogol/werkstatt-shared/share/agent";
+import { buildDnsAidRecord } from "@warpgogol/werkstatt-shared/agent";
+import type { AgentSurfaceManifest } from "@warpgogol/werkstatt-shared/agent";
 
 function makeManifest(baseUrl: string): AgentSurfaceManifest {
   return {

package/src/agent/guidance.ts

@@ -0,0 +1,52 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1115: single rendering point for model-oriented capability descriptions.
+Composes the authored base description with the optional agentGuidance block
+(whenToUse, whenNotToUse, sideEffect, retrySemantics) into a multi-sentence
+description consumed verbatim by MCP tools/list and OpenAPI operation docs.
+</purpose>
+<non-goals>
+  <item>Do not restate the RFC-1112 Idempotency-Key mechanism — retrySemantics
+        text is authored in capability YAMLs and passed through unchanged.</item>
+  <item>Do not localize — callers pick the base description language; guidance
+        fields are authored in English by design (capability YAMLs are global,
+        not per-site) — English is the model-facing lingua franca.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1115: initial — renderAgentGuidanceDescription composer.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { CapabilityRecord } from "@warpgogol/werkstatt-shared/ontology";
+
+/** The optional agentGuidance block on a capability record (RFC-1115). */
+export type CapabilityAgentGuidance = NonNullable<CapabilityRecord["agentGuidance"]>;
+
+/**
+ * Compose a tool/operation description from the base description and the
+ * optional agentGuidance block. Guidance absent → the base description is
+ * returned unchanged (AC-5 fallback).
+ */
+export function renderAgentGuidanceDescription(
+  base: string,
+  guidance: CapabilityAgentGuidance | undefined,
+): string {
+  if (!guidance) return base;
+
+  const sentences: string[] = [base];
+  sentences.push(`Use this when ${guidance.whenToUse}`);
+  if (guidance.whenNotToUse) {
+    sentences.push(`Do not use this when ${guidance.whenNotToUse}`);
+  }
+  sentences.push(
+    guidance.sideEffect === "write"
+      ? "This action has side effects — it submits a write to the business."
+      : "This action is side-effect free — it validates input and returns a preview without dispatching anything.",
+  );
+  if (guidance.retrySemantics) {
+    sentences.push(`Retry semantics: ${guidance.retrySemantics}`);
+  }
+  return sentences.join(" ");
+}

package/src/agent/health.ts

@@ -0,0 +1,68 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1116: contracts for the agent surface health endpoint and the external
+contract check. AgentHealth is the runtime response of GET /api/agent/health;
+AgentContractCheckResult is the diagnostics payload of the
+agent.surface.contract.check kernel command. The probe-id union is the closed
+vocabulary both sides share — the route emits "health", the command emits the
+full golden-journey list.
+</purpose>
+<non-goals>
+  <item>Do not implement probe logic here — the command lives in
+        @warpgogol/werkstatt-site/checks, the route factory in
+        @warpgogol/werkstatt-engine/agent-gate.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1116: initial contracts — AgentHealth, AgentContractCheckResult, AgentContractProbeId.</item>
+</CHANGE_SUMMARY>
+*/
+
+/** Response of GET /api/agent/health (RFC-1116). */
+export interface AgentHealth {
+  status: "ok" | "degraded";
+  /** AGENT_SURFACE_VERSION constant. */
+  surfaceVersion: string;
+  /** distTreeHash self-fetched from /.well-known/build-identity.json; "" when unavailable. */
+  contentHash: string;
+  checks: {
+    manifest: "ok" | "missing";
+    knowledge: "ok" | "missing";
+    /** QStash publish token present? */
+    dispatch: "configured" | "unconfigured";
+    search: "available" | "unavailable";
+  };
+}
+
+/**
+ * Closed probe-id vocabulary for the golden journey (RFC-1116). The command
+ * derives the active subset from the deployed agent.json — capabilities absent
+ * from the manifest yield `skipped` probes, not failures.
+ */
+export type AgentContractProbeId =
+  | "discovery.agent-json"
+  | "discovery.api-catalog"
+  | "discovery.llms"
+  | "knowledge.fetch"
+  | "mcp.initialize"
+  | "mcp.tools-list"
+  | "action.lead-prepare"
+  | "action.error-shape"
+  | "health";
+
+export interface AgentContractProbe {
+  id: AgentContractProbeId;
+  ok: boolean;
+  /** Capability absent from deployed agent.json, or agent.enabled: false. */
+  skipped?: boolean;
+  detail?: string;
+}
+
+/** Diagnostics payload of agent.surface.contract.check (RFC-1116, DNA-82). */
+export interface AgentContractCheckResult {
+  command: "agent.surface.contract.check";
+  status: "pass" | "fail";
+  url: string;
+  probes: AgentContractProbe[];
+}

package/src/{share/agent → agent}/index.ts

@@ -10,11 +10,12 @@ here (knowledge, capability, openapi, proof) and re-export them from this barrel
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0286: initial barrel exporting the manifest module.</item>
   <item>RFC-0292: re-export fleet-catalog module.</item>
   <item>RFC-0783: re-export api-catalog and mcp-card modules.</item>
   <item>RFC-0786: re-export dns-aid module.</item>
   <item>RFC-0954: re-export search module.</item>
+  <item>RFC-1112: re-export receipt module (ActionReceipt, AgentProblemDetails, deriveActionEventId).</item>
+  <history>RFC-0286</history>
 </CHANGE_SUMMARY>
 */
 
@@ -30,3 +31,6 @@ export * from "./mcp-card.ts";
 export * from "./dns-aid.ts";
 export * from "./ard-catalog.ts";
 export * from "./search.ts";
+export * from "./receipt.ts";
+export * from "./guidance.ts";
+export * from "./health.ts";

package/src/{share/agent → agent}/manifest.ts

@@ -13,8 +13,13 @@ two runs on unchanged input are byte-identical (AS-7).
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0286: initial manifest contract and pure builder.</item>
-  <item>RFC-0954: add search interface to AgentSurfaceManifest.interfaces.</item>
+  <item>RFC-1112: bump AGENT_SURFACE_VERSION to 2.0.0 — action responses become ActionReceipt + problem+json.</item>
+  <item>RFC-1113: add $schema, generatedAt (excluded from contentHash), supportedProtocols; AgentProtocol closed vocabulary.</item>
+  <item>RFC-1113: align agent discovery surface with RFC 9727 and MCP 2026-07-28 stateless era</item>
+  <item>RFC-1114: add "a2a" to AgentProtocol and interfaces.a2a (url + protocolVersion).</item>
+  <item>RFC-1114: minimal real A2A endpoint + honest agent card</item>
+  <item>RFC-1115: search results flattened to citation shape (title, canonicalUrl, updatedAt, lang, type, score, text) under the existing 2.0.0 surface; capability agentGuidance rendered into tool/operation descriptions.</item>
+  <history>RFC-0286, RFC-0954, RFC-1076</history>
 </CHANGE_SUMMARY>
 */
 
@@ -22,7 +27,28 @@ import { createHash } from "node:crypto";
 import type { AgentSurfaceProof } from "./proof.ts";
 
 /** Semver of THIS manifest schema. Bump only via an RFC amending RFC-0286 (AS-7). */
-export const AGENT_SURFACE_VERSION = "1.0.0";
+export const AGENT_SURFACE_VERSION = "2.0.0";
+
+/** RFC-1113: $schema identifier for the Agent Surface Manifest document. */
+export const AGENT_SURFACE_SCHEMA_ID = "gogol.agent.surface/2";
+
+/**
+ * RFC-1113: closed vocabulary for AgentSurfaceManifest.supportedProtocols.
+ * Every value MUST correspond to a discovery artifact or interface the surface
+ * actually emits — agent.surface.validate enforces the honesty invariant
+ * (AGS-DISCOVERY-01).
+ */
+export type AgentProtocol =
+  | "mcp"
+  | "a2a"
+  | "openapi"
+  | "linkset"
+  | "llms"
+  | "twins"
+  | "ard"
+  | "dns-aid"
+  | "agent-skills"
+  | "search";
 
 export interface AgentKnowledgeRef {
   /** A BusinessDomain with visibility "public" (RFC-0287). */
@@ -41,20 +67,38 @@ export interface AgentActionRef {
   entitlement: "agent.actions";
 }
 
+export interface AgentClaimRef {
+  id: string;
+  claimClass: string;
+  statement: string;
+  verificationLevel?: string;
+  evidenceCount: number;
+}
+
 export interface AgentSurfaceManifest {
+  /** RFC-1113: schema identifier — "gogol.agent.surface/2". */
+  $schema: string;
   surfaceVersion: string;
   site: string;
   baseUrl: string;
   languages: { default: string; supported: string[] };
-  /** sha256 hex over sorted-key JSON of this document minus contentHash + proof. */
+  /** RFC-1113: ISO 8601 build timestamp — excluded from contentHash + signing payload. */
+  generatedAt: string;
+  /** RFC-1113: closed vocabulary — only the protocols this surface actually emits. */
+  supportedProtocols: AgentProtocol[];
+  /** sha256 hex over sorted-key JSON of this document minus contentHash + proof + generatedAt. */
   contentHash: string;
   knowledge: AgentKnowledgeRef[];
   actions: AgentActionRef[];
+  /** RFC-1076: claim provenance chain — claims with their evidence references. */
+  claims: AgentClaimRef[];
   interfaces: {
     llms: string;
     twins: { pattern: string } | null;
     openapi: string | null;
     mcp: { url: string; protocolVersion: string } | null;
+    /** RFC-1114: the A2A endpoint — null when the surface ships no A2A route. */
+    a2a: { url: string; protocolVersion: string } | null;
     search: { url: string; model: string; dimensions: number } | null;
   };
   /** Null until agent.surface.sign signs it (RFC-0308) or when no key material exists. */
@@ -65,11 +109,17 @@ export interface AgentSurfaceManifestInput {
   site: string;
   baseUrl: string;
   languages: { default: string; supported: string[] };
+  /** RFC-1113: ISO 8601 build timestamp supplied by the caller (the builder stays pure). */
+  generatedAt: string;
   knowledge?: AgentKnowledgeRef[];
   actions?: AgentActionRef[];
+  /** RFC-1076: claim provenance summaries for the manifest. */
+  claims?: AgentClaimRef[];
   hasTwins?: boolean;
   openapiUrl?: string | null;
   mcp?: { url: string; protocolVersion: string } | null;
+  /** RFC-1114: the A2A endpoint descriptor — omit/null when no A2A route exists. */
+  a2a?: { url: string; protocolVersion: string } | null;
   search?: { url: string; model: string; dimensions: number } | null;
 }
 
@@ -114,9 +164,13 @@ export function computeSignedContentHash(
   return createHash("sha256").update(canonicalJson(rest), "utf8").digest("hex");
 }
 
-/** sha256 hex over the canonical JSON of `doc` with `contentHash` and `proof` removed. */
+/**
+ * sha256 hex over the canonical JSON of `doc` with `contentHash`, `proof`, and
+ * `generatedAt` removed. RFC-1113: `generatedAt` is a build timestamp — including
+ * it would produce a spurious hash (and signature) change on every rebuild.
+ */
 export function computeAgentManifestContentHash(doc: Record<string, unknown>): string {
-  return computeSignedContentHash(doc);
+  return computeSignedContentHash(doc, ["generatedAt"]);
 }
 
 // ---------------------------------------------------------------------------
@@ -125,21 +179,44 @@ export function computeAgentManifestContentHash(doc: Record<string, unknown>): s
 
 /** Pure: assemble + hash the manifest. Deterministic — sorts refs and languages. */
 export function buildAgentSurfaceManifest(input: AgentSurfaceManifestInput): AgentSurfaceManifest {
+  // RFC-1113: honesty invariant — supportedProtocols lists only what the surface
+  // emits. The unconditional entries are the artifacts every enabled agent
+  // surface generates (llms.txt, api-catalog linkset, ai-catalog ARD document,
+  // DNS-AID record, agent-skills index); the conditional ones follow interfaces.
+  const supportedProtocols: AgentProtocol[] = (
+    [
+      "agent-skills",
+      "ard",
+      "dns-aid",
+      "linkset",
+      "llms",
+      ...(input.mcp ? ["mcp"] : []),
+      ...(input.a2a ? ["a2a"] : []),
+      ...(input.openapiUrl ? ["openapi"] : []),
+      ...(input.search ? ["search"] : []),
+      ...(input.hasTwins ? ["twins"] : []),
+    ] as AgentProtocol[]
+  ).sort();
   const base: Omit<AgentSurfaceManifest, "contentHash"> = {
+    $schema: AGENT_SURFACE_SCHEMA_ID,
     surfaceVersion: AGENT_SURFACE_VERSION,
     site: input.site,
     baseUrl: input.baseUrl.replace(/\/+$/, ""),
+    generatedAt: input.generatedAt,
+    supportedProtocols,
     languages: {
       default: input.languages.default,
       supported: [...input.languages.supported].sort(),
     },
     knowledge: [...(input.knowledge ?? [])].sort((a, b) => a.domain.localeCompare(b.domain)),
     actions: [...(input.actions ?? [])].sort((a, b) => a.id.localeCompare(b.id)),
+    claims: [...(input.claims ?? [])].sort((a, b) => a.id.localeCompare(b.id)),
     interfaces: {
       llms: "/llms.txt",
       twins: input.hasTwins ? { pattern: "/**.md" } : null,
       openapi: input.openapiUrl ?? null,
       mcp: input.mcp ?? null,
+      a2a: input.a2a ?? null,
       search: input.search ?? null,
     },
     proof: null,

package/src/{share/agent → agent}/openapi.ts

@@ -16,11 +16,14 @@ copied verbatim (AGO-04 enforces this).
 <CHANGE_SUMMARY>
   <item>RFC-0289: initial OpenAPI projection.</item>
   <item>RFC-0954: add /api/agent/search path with dynamic lang enum from manifest.languages.supported.</item>
+  <item>RFC-1112: Idempotency-Key header param + application/problem+json error responses on action paths.</item>
+  <item>RFC-1115: agentGuidance rendered into operation descriptions; search-response schema matches the flattened citation shape.</item>
 </CHANGE_SUMMARY>
 */
 
 import type { AgentSurfaceManifest } from "./manifest.ts";
 import type { CapabilityInputOutputSchema } from "@warpgogol/werkstatt-shared/ontology";
+import { renderAgentGuidanceDescription, type CapabilityAgentGuidance } from "./guidance.ts";
 
 export interface OpenApiSchemaObject {
   type: string;
@@ -33,6 +36,7 @@ export interface OpenApiSchemaObject {
 export interface OpenApiOperation {
   operationId: string;
   summary?: string;
+  description?: string;
   tags: string[];
   parameters?: Array<{
     name: string;
@@ -47,7 +51,12 @@ export interface OpenApiOperation {
   };
   responses: Record<
     string,
-    { description: string; content?: { "application/json": { schema: unknown } } }
+    {
+      description: string;
+      content?: Partial<
+        Record<"application/json" | "application/problem+json", { schema: unknown }>
+      >;
+    }
   >;
 }
 
@@ -67,6 +76,66 @@ export interface CapabilitySchemaInput {
   id: string;
   input: CapabilityInputOutputSchema;
   output: CapabilityInputOutputSchema;
+  /** RFC-1115: localized base description for operation docs. */
+  description?: Record<string, string>;
+  /** RFC-1115: model-oriented guidance rendered into the operation description. */
+  agentGuidance?: CapabilityAgentGuidance;
+}
+
+/** RFC-1112: shared RFC 9457 problem-details schema referenced by every action error response. */
+function problemDetailsSchema(): Record<string, unknown> {
+  return {
+    type: "object",
+    required: ["type", "title", "status", "code", "retryable"],
+    properties: {
+      type: { type: "string" },
+      title: { type: "string" },
+      status: { type: "integer" },
+      detail: { type: "string" },
+      code: {
+        type: "string",
+        enum: [
+          "invalid-json",
+          "schema-violation",
+          "unknown-capability",
+          "payload-too-large",
+          "rate-limited",
+          "dispatch-failed",
+          "idempotency-key-reuse",
+        ],
+      },
+      retryable: { type: "boolean" },
+      errors: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: { path: { type: "string" }, message: { type: "string" } },
+        },
+      },
+      schemaRef: { type: "string" },
+      retryAfterSeconds: { type: "integer" },
+    },
+  };
+}
+
+/** RFC-1112: the standard error responses every action path declares. */
+function actionErrorResponses(): OpenApiOperation["responses"] {
+  const problem = {
+    "application/problem+json": {
+      schema: { $ref: "#/components/schemas/problem-details" },
+    },
+  };
+  return {
+    "400": { description: "Request body is not valid JSON", content: problem },
+    "409": {
+      description: "Idempotency-Key was used with a different payload",
+      content: problem,
+    },
+    "413": { description: "Payload exceeds the capability limit", content: problem },
+    "422": { description: "Input failed schema validation", content: problem },
+    "429": { description: "Rate limit exceeded", content: problem },
+    "502": { description: "Delivery substrate rejected the event", content: problem },
+  };
 }
 
 /** Generic envelope schema — every knowledge domain shares this wrapper shape (RFC-0287); only `data`'s inner shape varies by domain and is intentionally left untyped here. */
@@ -118,16 +187,35 @@ export function formatAgentOpenApi(
     };
   }
 
+  componentSchemas["problem-details"] = problemDetailsSchema();
+
   for (const ref of manifest.actions) {
     const schemas = schemasById.get(ref.id);
     if (!schemas) continue; // defensive — AGO-04-checked at validate time
     componentSchemas[`${ref.id}-input`] = schemas.input;
     componentSchemas[`${ref.id}-output`] = schemas.output;
+    // RFC-1115: agentGuidance composes a model-oriented operation description;
+    // absent guidance falls back to the base capability description.
+    const baseDescription =
+      schemas.description?.[manifest.languages.default] ??
+      ref.title[manifest.languages.default] ??
+      ref.id;
     paths[ref.url] = {
       post: {
         operationId: `action.${ref.id}`,
         summary: ref.title[manifest.languages.default] ?? ref.id,
+        description: renderAgentGuidanceDescription(baseDescription, schemas.agentGuidance),
         tags: ["actions"],
+        parameters: [
+          {
+            name: "Idempotency-Key",
+            in: "header",
+            required: false,
+            schema: { type: "string", maxLength: 255 },
+            description:
+              "Optional dedup key. Repeating a request with the same key and body returns the original receipt; the same key with a different body is rejected with 409.",
+          },
+        ],
         requestBody: {
           required: true,
           content: { "application/json": { schema: schemas.input } },
@@ -137,8 +225,7 @@ export function formatAgentOpenApi(
             description: `${ref.id} accepted`,
             content: { "application/json": { schema: schemas.output } },
           },
-          "400": { description: "Schema violation" },
-          "429": { description: "Rate limit exceeded" },
+          ...actionErrorResponses(),
         },
       },
     };
@@ -154,9 +241,15 @@ export function formatAgentOpenApi(
           type: "array",
           items: {
             type: "object",
+            required: ["title", "canonicalUrl", "updatedAt", "lang", "type", "score", "text"],
             properties: {
-              chunk: { type: "object" },
+              title: { type: ["string", "null"] },
+              canonicalUrl: { type: "string" },
+              updatedAt: { type: ["string", "null"] },
+              lang: { type: "string" },
+              type: { type: "string", enum: ["page", "knowledge", "faq", "prose"] },
               score: { type: "number" },
+              text: { type: "string" },
             },
           },
         },

package/src/agent/receipt.ts

@@ -0,0 +1,123 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1112: canonical agent-action receipt + RFC 9457 problem-details contracts.
+One shape for both invocation surfaces (HTTP POST /api/agent/actions/{id} and
+MCP tools/call) — the receipt is the final v1 answer; errors carry a stable
+machine `code` so agents can branch without parsing prose.
+</purpose>
+<non-goals>
+  <item>Do not store or transport lead payload fields — receipts carry
+        identifiers and timestamps only (no PII at rest).</item>
+  <item>Do not add transport logic — HTTP/MCP mapping lives in the engine
+        (action-pipeline.ts, mcp/handler.ts).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1112: initial receipt/problem-details contracts + deterministic eventId derivation.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { byteHash } from "@warpgogol/werkstatt-shared/fingerprint";
+
+/**
+ * The single response shape for a successful agent action invocation (RFC-1112).
+ * `receiptId` equals `IntegrationEvent.eventId` — deterministic when the caller
+ * supplied an Idempotency-Key, random otherwise.
+ */
+export interface ActionReceipt {
+  receiptId: string;
+  status: "accepted" | "duplicate";
+  duplicate: boolean;
+  /** ISO 8601 — stamped by the dispatch adapter at publish time. */
+  submittedAt: string;
+}
+
+/** Stable machine codes for agent-action failures (RFC-1112). Closed set. */
+export type AgentErrorCode =
+  | "invalid-json"
+  | "schema-violation"
+  | "unknown-capability"
+  | "payload-too-large"
+  | "rate-limited"
+  | "dispatch-failed"
+  | "idempotency-key-reuse";
+
+/** RFC 9457 problem details with platform extension members (`code`, `retryable`, …). */
+export interface AgentProblemDetails {
+  type: string;
+  title: string;
+  status: number;
+  detail?: string;
+  code: AgentErrorCode;
+  retryable: boolean;
+  /** Per-field violations for schema-violation. */
+  errors?: { path: string; message: string }[];
+  /** Pointer into agent.openapi.json for schema-violation. */
+  schemaRef?: string;
+  /** Seconds until the rate-limit window resets (rate-limited only). */
+  retryAfterSeconds?: number;
+}
+
+export const AGENT_ERROR_STATUS: Record<AgentErrorCode, number> = {
+  "invalid-json": 400,
+  "schema-violation": 422,
+  "unknown-capability": 404,
+  "payload-too-large": 413,
+  "rate-limited": 429,
+  "dispatch-failed": 502,
+  "idempotency-key-reuse": 409,
+};
+
+export const AGENT_ERROR_RETRYABLE: Record<AgentErrorCode, boolean> = {
+  "invalid-json": false,
+  "schema-violation": false,
+  "unknown-capability": false,
+  "payload-too-large": false,
+  "rate-limited": true,
+  "dispatch-failed": true,
+  "idempotency-key-reuse": false,
+};
+
+const AGENT_ERROR_TITLE: Record<AgentErrorCode, string> = {
+  "invalid-json": "Request body is not valid JSON",
+  "schema-violation": "Input failed schema validation",
+  "unknown-capability": "Unknown capability",
+  "payload-too-large": "Payload exceeds the capability limit",
+  "rate-limited": "Rate limit exceeded",
+  "dispatch-failed": "Delivery substrate rejected the event",
+  "idempotency-key-reuse": "Idempotency-Key was used with a different payload",
+};
+
+/** Build a problem-details object for `code`; status/title/retryable derive from the closed tables. */
+export function buildAgentProblem(
+  code: AgentErrorCode,
+  init?: Partial<Omit<AgentProblemDetails, "type" | "status" | "code" | "retryable">>,
+): AgentProblemDetails {
+  return {
+    type: "about:blank",
+    title: AGENT_ERROR_TITLE[code],
+    status: AGENT_ERROR_STATUS[code],
+    code,
+    retryable: AGENT_ERROR_RETRYABLE[code],
+    ...(init?.detail !== undefined ? { detail: init.detail } : {}),
+    ...(init?.errors !== undefined ? { errors: init.errors } : {}),
+    ...(init?.schemaRef !== undefined ? { schemaRef: init.schemaRef } : {}),
+    ...(init?.retryAfterSeconds !== undefined
+      ? { retryAfterSeconds: init.retryAfterSeconds }
+      : {}),
+  };
+}
+
+/**
+ * RFC-1112: deterministic eventId/receiptId from an Idempotency-Key.
+ * sha256("gogol-agent-action:" + capabilityId + ":" + key), first 32 hex chars
+ * formatted as a UUID. Same key + same capability → same eventId, so QStash
+ * deduplication and the receipt store agree on identity.
+ */
+export function deriveActionEventId(capabilityId: string, idempotencyKey: string): string {
+  const hex = byteHash(`gogol-agent-action:${capabilityId}:${idempotencyKey}`).slice(
+    "sha256:".length,
+  );
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}

package/src/{share/agent → agent}/search.test.ts

@@ -19,6 +19,9 @@ const baseChunk: SearchChunk = {
   blockId: "block-intro",
   heading: "About",
   text: "About the company",
+  title: "About",
+  canonicalUrl: "https://example.example/about",
+  updatedAt: "2026-08-20",
 };
 
 describe("buildSearchManifest", () => {