@lssm/lib.contracts-spec 17.3.2

package/dist/agent/protocol/reflection.d.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { type AgentExecutionVerificationViewV1 } from './common.js';
+import type { AgentCheckpointV1, AgentTerminalDecisionV1 } from './execution.js';
+import type { AgentExecutionPlanV1 } from './planning.js';
+export declare const AGENT_REFLECTION_V1: 'contractspec.agent.reflection.v1';
+/** Reflection is an evidence-backed recommendation and has no effect authority. */
+export declare const agentReflectionV1Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"contractspec.agent.reflection.v1">;
+    id: z.ZodString;
+    runRef: z.ZodString;
+    epochRef: z.ZodString;
+    checkpointRef: z.ZodString;
+    expectedOutcomeSummary: z.ZodString;
+    observedOutcomeSummary: z.ZodString;
+    evidenceInspected: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            eval_result: "eval_result";
+            human_feedback: "human_feedback";
+            policy_decision: "policy_decision";
+            redaction_decision: "redaction_decision";
+            replay_bundle: "replay_bundle";
+            retrieval_context: "retrieval_context";
+            rollback_version: "rollback_version";
+            source_message: "source_message";
+            tool_receipt: "tool_receipt";
+        }>;
+        ref: z.ZodString;
+        sourcePackage: z.ZodString;
+        redactionStatus: z.ZodEnum<{
+            none: "none";
+            redacted: "redacted";
+            restricted: "restricted";
+        }>;
+        ontologyRef: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodString;
+        artifactHash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    constraintsStillSatisfied: z.ZodArray<z.ZodString>;
+    constraintViolations: z.ZodArray<z.ZodString>;
+    contextGapRefs: z.ZodArray<z.ZodString>;
+    budgetSnapshotRef: z.ZodString;
+    budgetVarianceSummary: z.ZodString;
+    uncertaintyRefs: z.ZodArray<z.ZodString>;
+    failureRefs: z.ZodArray<z.ZodString>;
+    progressEvidenceRefs: z.ZodArray<z.ZodString>;
+    recommendation: z.ZodObject<{
+        decision: z.ZodEnum<{
+            blocked: "blocked";
+            cancelled: "cancelled";
+            complete: "complete";
+            continue: "continue";
+            delegate: "delegate";
+            replan: "replan";
+            request_approval: "request_approval";
+            request_help: "request_help";
+        }>;
+        reasonSummary: z.ZodString;
+        nextPlanRef: z.ZodOptional<z.ZodString>;
+        helpRequestRef: z.ZodOptional<z.ZodString>;
+        approvalRequestRef: z.ZodOptional<z.ZodString>;
+        delegationRef: z.ZodOptional<z.ZodString>;
+        terminalDecisionCandidateRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    createdAt: z.ZodString;
+}, z.core.$strict>;
+export type AgentReflectionV1 = z.infer<typeof agentReflectionV1Schema>;
+export declare function validateAgentTerminalDecisionBindingV1(input: {
+    plan: AgentExecutionPlanV1;
+    checkpoint: AgentCheckpointV1;
+    decision: AgentTerminalDecisionV1;
+    canonicalVerification?: AgentExecutionVerificationViewV1;
+}): string[];

package/dist/agent/protocol/reflection.js

@@ -0,0 +1 @@
+import{z as n}from"zod";import{agentProtocolEvidencePointerSchema as l,agentProtocolRefSchema as e,agentProtocolTimestampSchema as p,validateAgentExecutionVerificationV1 as f}from"./common.js";export const AGENT_REFLECTION_V1="contractspec.agent.reflection.v1";const d=n.object({decision:n.enum(["continue","replan","request_help","request_approval","delegate","complete","blocked","cancelled"]),reasonSummary:e,nextPlanRef:e.optional(),helpRequestRef:e.optional(),approvalRequestRef:e.optional(),delegationRef:e.optional(),terminalDecisionCandidateRef:e.optional()}).strict().superRefine((a,t)=>{const i={replan:"nextPlanRef",request_help:"helpRequestRef",request_approval:"approvalRequestRef",delegate:"delegationRef",complete:"terminalDecisionCandidateRef",blocked:"terminalDecisionCandidateRef",cancelled:"terminalDecisionCandidateRef"}[a.decision];if(i&&!a[i])t.addIssue({code:n.ZodIssueCode.custom,path:[i],message:`${a.decision} requires ${i}`})});export const agentReflectionV1Schema=n.object({schemaVersion:n.literal(AGENT_REFLECTION_V1),id:e,runRef:e,epochRef:e,checkpointRef:e,expectedOutcomeSummary:e,observedOutcomeSummary:e,evidenceInspected:n.array(l),constraintsStillSatisfied:n.array(e),constraintViolations:n.array(e),contextGapRefs:n.array(e),budgetSnapshotRef:e,budgetVarianceSummary:e,uncertaintyRefs:n.array(e),failureRefs:n.array(e),progressEvidenceRefs:n.array(e),recommendation:d,createdAt:p}).strict();export function validateAgentTerminalDecisionBindingV1(a){const{plan:t,checkpoint:c,decision:i}=a,o=[];if(i.plan.ref!==t.id||i.plan.digest!==t.planDigest)o.push("Terminal decision plan binding does not match");if(i.runRef!==c.runRef||i.checkpointRef!==c.id)o.push("Terminal decision checkpoint binding does not match");if(c.plan.ref!==t.id||c.plan.digest!==t.planDigest)o.push("Terminal checkpoint plan does not match");if(t.scope.runId&&t.scope.runId!==i.runRef)o.push("Terminal decision run does not match the plan scope");if(i.riskTier!==t.riskTier)o.push("Terminal decision changes plan risk tier");if(i.decision!=="complete")return o;const s=i.completionCriteria.map((r)=>r.criterionRef);if(new Set(s).size!==s.length)o.push("Terminal decision completion criteria must be unique");if(JSON.stringify([...s].sort())!==JSON.stringify([...t.completionCriteria].sort()))o.push("Terminal decision completion criteria do not match the plan");for(const r of i.completionCriteria)if(!r.satisfied||r.evidenceRefs.length===0)o.push(`Terminal decision does not prove plan criterion: ${r.criterionRef}`);o.push(...f({expectedPolicyRef:t.verificationPolicyRef,binding:i.verification,canonical:a.canonicalVerification}));return o}

package/dist/agent/protocol/task-result-validation.d.ts

@@ -0,0 +1,6 @@
+import type { AgentDelegationV1, AgentTaskGraphPlanV1, AgentTaskResultV1 } from './delegation.js';
+export declare function validateAgentTaskResultBindingV1(input: {
+    graph: AgentTaskGraphPlanV1;
+    delegation: AgentDelegationV1;
+    result: AgentTaskResultV1;
+}): string[];

package/dist/agent/protocol/task-result-validation.js

@@ -0,0 +1 @@
+function o(r,i){return r.ref===i.ref&&r.digest===i.digest}function f(r){return new Set(r).size!==r.length}function d(r,i){return JSON.stringify([...r].sort())===JSON.stringify([...i].sort())}export function validateAgentTaskResultBindingV1(r){const{graph:i,delegation:s,result:n}=r,e=[],a=i.tasks.find((t)=>t.id===n.taskRef);if(!o(n.taskGraph,{ref:i.id,digest:i.graphDigest}))e.push("Task result graph binding does not match");if(!o(s.taskGraph,{ref:i.id,digest:i.graphDigest})||s.runRef!==i.runRef)e.push("Task result delegation does not belong to the graph run");if(!a)return[...e,"Task result references an unknown task"];if(n.taskRef!==s.taskRef||!o(n.delegation,{ref:s.id,digest:s.delegationDigest}))e.push("Task result delegation binding does not match");if(n.producerPrincipalRef!==s.derivedPrincipalRef)e.push("Task result producer does not match the delegated principal");if(n.status!=="ready_for_verification")return e;if(f(n.artifactRefs))e.push("Task result artifact references must be unique");for(const t of a.expectedArtifactRefs)if(!n.artifactRefs.includes(t))e.push(`Task result is missing declared artifact: ${t}`);const u=n.evidenceSatisfactions.map((t)=>t.requirementRef);if(f(u))e.push("Task result evidence requirements must be unique");if(!d(u,a.requiredEvidenceKinds))e.push("Task result evidence requirements do not match its task");const c=n.completionCriteria.map((t)=>t.criterionRef);if(f(c))e.push("Task result completion criteria must be unique");if(!d(c,a.completionCriteria))e.push("Task result completion criteria do not match its task");for(const t of n.completionCriteria)if(!t.satisfied||t.evidenceRefs.length===0)e.push(`Task result does not prove criterion: ${t.criterionRef}`);return e}

package/dist/agent/queries/agentArtifacts.query.d.ts

@@ -0,0 +1,68 @@
+import { SchemaModel } from '@lssm/lib.schema';
+export declare const AgentArtifactsDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+export declare const AgentArtifactsQuery: import("../..").OperationSpec<SchemaModel<{
+    runId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    kind: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    limit: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+    offset: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+}>, SchemaModel<{
+    artifacts: {
+        type: SchemaModel<{
+            artifactId: {
+                type: import("@lssm/lib.schema").FieldType<string, string>;
+                isOptional: false;
+            };
+            kind: {
+                type: import("@lssm/lib.schema").FieldType<string, string>;
+                isOptional: false;
+            };
+            uri: {
+                type: import("@lssm/lib.schema").FieldType<string, string>;
+                isOptional: false;
+            };
+            contentType: {
+                type: import("@lssm/lib.schema").FieldType<string, string>;
+                isOptional: true;
+            };
+            summary: {
+                type: import("@lssm/lib.schema").FieldType<string, string>;
+                isOptional: true;
+            };
+            createdAt: {
+                type: import("@lssm/lib.schema").FieldType<Date, string>;
+                isOptional: false;
+            };
+        }>;
+        isOptional: false;
+        isArray: true;
+    };
+    total: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+    nextOffset: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+}>, undefined>;

package/dist/agent/queries/agentArtifacts.query.js

@@ -0,0 +1,4 @@
+import{ScalarTypeEnum as t,SchemaModel as e}from"@lssm/lib.schema";import{docId as i}from"../../docs/registry.js";import{defineQuery as a}from"../../operations/index.js";import{AGENT_DOMAIN as n,AGENT_OWNERS as s,AGENT_STABILITY as r,AGENT_TAGS as o}from"../constants.js";const c=new e({name:"AgentArtifactsInput",fields:{runId:{type:t.ID(),isOptional:!1},kind:{type:t.String_unsecure(),isOptional:!0},limit:{type:t.Int_unsecure(),isOptional:!0},offset:{type:t.Int_unsecure(),isOptional:!0}}});const u=new e({name:"AgentArtifact",fields:{artifactId:{type:t.ID(),isOptional:!1},kind:{type:t.String_unsecure(),isOptional:!1},uri:{type:t.String_unsecure(),isOptional:!1},contentType:{type:t.String_unsecure(),isOptional:!0},summary:{type:t.String_unsecure(),isOptional:!0},createdAt:{type:t.DateTime(),isOptional:!1}}});const p=new e({name:"AgentArtifactsOutput",fields:{artifacts:{type:u,isOptional:!1,isArray:!0},total:{type:t.Int_unsecure(),isOptional:!0},nextOffset:{type:t.Int_unsecure(),isOptional:!0}}});export const AgentArtifactsDocBlock={id:"docs.tech.agent.artifacts",title:"Agent artifacts",summary:"List artifacts produced by an agent run.",kind:"reference",visibility:"public",route:"/docs/tech/agent/artifacts",tags:["agent","artifacts"],body:`# agent.artifacts
+
+Lists files, diffs, and outputs produced during agent execution.
+`};export const AgentArtifactsQuery=a({meta:{key:"agent.artifacts",title:"Agent Run Artifacts",version:"1.0.0",description:"List artifacts produced by an agent run.",goal:"Provide traceable outputs for audits and UI surfaces.",context:"Used by Studio to show diffs, files, and run outputs.",domain:n,owners:s,tags:[...o,"artifacts"],stability:r,docId:[i("docs.tech.agent.artifacts")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:c,output:p},policy:{auth:"user",pii:[]}});

package/dist/agent/queries/agentStatus.query.d.ts

@@ -0,0 +1,76 @@
+import { SchemaModel } from '@lssm/lib.schema';
+export declare const AgentStatusDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+export declare const AgentStatusQuery: import("../..").OperationSpec<SchemaModel<{
+    runId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    status: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    limit: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+    offset: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+}>, SchemaModel<{
+    runs: {
+        type: SchemaModel<{
+            runId: {
+                type: import("@lssm/lib.schema").FieldType<string, string>;
+                isOptional: false;
+            };
+            agentKey: {
+                type: import("@lssm/lib.schema").FieldType<string, string>;
+                isOptional: false;
+            };
+            status: {
+                type: import("@lssm/lib.schema").FieldType<string, string>;
+                isOptional: false;
+            };
+            submittedAt: {
+                type: import("@lssm/lib.schema").FieldType<Date, string>;
+                isOptional: false;
+            };
+            startedAt: {
+                type: import("@lssm/lib.schema").FieldType<Date, string>;
+                isOptional: true;
+            };
+            completedAt: {
+                type: import("@lssm/lib.schema").FieldType<Date, string>;
+                isOptional: true;
+            };
+            contextSnapshotId: {
+                type: import("@lssm/lib.schema").FieldType<string, string>;
+                isOptional: true;
+            };
+            lastError: {
+                type: import("@lssm/lib.schema").FieldType<string, string>;
+                isOptional: true;
+            };
+        }>;
+        isOptional: false;
+        isArray: true;
+    };
+    total: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+    nextOffset: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+}>, undefined>;

package/dist/agent/queries/agentStatus.query.js

@@ -0,0 +1,4 @@
+import{ScalarTypeEnum as t,SchemaModel as e}from"@lssm/lib.schema";import{docId as s}from"../../docs/registry.js";import{defineQuery as n}from"../../operations/index.js";import{AGENT_DOMAIN as a,AGENT_OWNERS as i,AGENT_STABILITY as u,AGENT_TAGS as o}from"../constants.js";const r=new e({name:"AgentStatusInput",fields:{runId:{type:t.ID(),isOptional:!0},status:{type:t.String_unsecure(),isOptional:!0},limit:{type:t.Int_unsecure(),isOptional:!0},offset:{type:t.Int_unsecure(),isOptional:!0}}});const p=new e({name:"AgentRunSummary",fields:{runId:{type:t.ID(),isOptional:!1},agentKey:{type:t.String_unsecure(),isOptional:!1},status:{type:t.String_unsecure(),isOptional:!1},submittedAt:{type:t.DateTime(),isOptional:!1},startedAt:{type:t.DateTime(),isOptional:!0},completedAt:{type:t.DateTime(),isOptional:!0},contextSnapshotId:{type:t.ID(),isOptional:!0},lastError:{type:t.String_unsecure(),isOptional:!0}}});const c=new e({name:"AgentStatusOutput",fields:{runs:{type:p,isOptional:!1,isArray:!0},total:{type:t.Int_unsecure(),isOptional:!0},nextOffset:{type:t.Int_unsecure(),isOptional:!0}}});export const AgentStatusDocBlock={id:"docs.tech.agent.status",title:"Agent status",summary:"Query agent run status.",kind:"reference",visibility:"public",route:"/docs/tech/agent/status",tags:["agent","status"],body:`# agent.status
+
+Returns status summaries for one or many agent runs.
+`};export const AgentStatusQuery=n({meta:{key:"agent.status",title:"Agent Run Status",version:"1.0.0",description:"Get status for agent runs.",goal:"Provide status and progress visibility for background agents.",context:"Used by Studio and operators to monitor agent execution.",domain:a,owners:i,tags:[...o,"status"],stability:u,docId:[s("docs.tech.agent.status")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:r,output:c},policy:{auth:"user",pii:[]}});

package/dist/agent/queries/index.d.ts

@@ -0,0 +1,2 @@
+export * from './agentArtifacts.query.js';
+export * from './agentStatus.query.js';

package/dist/agent/queries/index.js

@@ -0,0 +1 @@
+export*from"./agentArtifacts.query.js";export*from"./agentStatus.query.js";

package/dist/agent/registry.d.ts

@@ -0,0 +1,41 @@
+import { SpecContractRegistry } from '../registry.js';
+import type { AgentSpec } from './spec.js';
+/**
+ * Registry for managing agent specifications.
+ *
+ * Provides registration, lookup, and version management for agent specs.
+ */
+export declare class AgentRegistry extends SpecContractRegistry<'agent', AgentSpec> {
+    constructor(items?: AgentSpec[]);
+    /**
+     * List all unique agent names (without versions).
+     */
+    listNames(): string[];
+    /**
+     * Get an agent specification or throw if not found.
+     *
+     * @param name - Agent name
+     * @param version - Optional version
+     * @returns The agent spec
+     * @throws Error if the spec is not found
+     */
+    require(name: string, version?: string): AgentSpec;
+    /**
+     * Check if an agent is registered.
+     *
+     * @param name - Agent name
+     * @param version - Optional version
+     */
+    has(name: string, version?: string): boolean;
+    /**
+     * Get all versions of an agent.
+     *
+     * @param name - Agent name
+     * @returns Array of specs sorted by version (ascending)
+     */
+    getVersions(name: string): AgentSpec[];
+}
+/**
+ * Create a new agent registry.
+ */
+export declare function createAgentRegistry(): AgentRegistry;

package/dist/agent/registry.js

@@ -0,0 +1 @@
+import{compareVersions as s}from"compare-versions";import{SpecContractRegistry as o}from"../registry.js";export class AgentRegistry extends o{constructor(e){super("agent",e)}listNames(){const e=new Set;for(const t of this.items.values())e.add(t.meta.key);return[...e]}require(e,t){const r=this.get(e,t);if(!r)throw Error(`Agent spec not found for ${e}${t!=null?`.v${t}`:""}`);return r}has(e,t){return this.get(e,t)!==void 0}getVersions(e){const t=[];for(const r of this.items.values())if(r.meta.key===e)t.push(r);return t.sort((r,n)=>s(r.meta.version,n.meta.version))}}export function createAgentRegistry(){return new AgentRegistry}

package/dist/agent/runner.d.ts

@@ -0,0 +1,62 @@
+import type { AgentTask } from './task-tree.js';
+/** Lifecycle event types emitted by the agent task runner. */
+export type AgentRunnerEventType = 'agent.task_started' | 'agent.task_completed' | 'agent.task_failed' | 'agent.task_cancelled';
+/** Event emitted by the runner on each task lifecycle transition. */
+export interface AgentRunnerEvent {
+    /** Lifecycle event type. */
+    readonly type: AgentRunnerEventType;
+    /** ID of the task this event refers to. */
+    readonly taskId: string;
+    /** Error message — present only for `agent.task_failed`. */
+    readonly error?: string;
+}
+/** Callback invoked for every lifecycle event. */
+export type AgentRunnerEventHandler = (event: AgentRunnerEvent) => void;
+/**
+ * Mutable cancel signal. Set `cancelled = true` at any point to stop
+ * the current tree walk; all tasks not yet started are cancelled.
+ */
+export interface AgentCancelSignal {
+    cancelled: boolean;
+}
+/** Create a fresh, uncancelled {@link AgentCancelSignal}. */
+export declare function createCancelSignal(): AgentCancelSignal;
+/** Options accepted by {@link runAgentTaskTree}. */
+export interface RunAgentTaskTreeOptions {
+    /**
+     * Called synchronously for each task. Throwing causes the task to be
+     * recorded as failed and the walk to stop for that branch.
+     */
+    execute: (task: AgentTask) => void;
+    /** Optional lifecycle event sink. */
+    onEvent?: AgentRunnerEventHandler;
+    /** Optional cancel signal; set `.cancelled = true` to abort. */
+    cancelSignal?: AgentCancelSignal;
+}
+/**
+ * Execute a flat list of {@link AgentTask} records as a depth-first tree.
+ *
+ * Parent tasks are executed before their children. Tasks with no `parent`
+ * are treated as roots; multiple roots are walked in array order.
+ *
+ * Cancellation: if `options.cancelSignal.cancelled` is `true` when a task
+ * is about to start, that task and all its descendants receive
+ * `agent.task_cancelled` events and are not executed.
+ *
+ * Failure: if `options.execute` throws for a task, the task emits
+ * `agent.task_failed` and its subtree is skipped (siblings still run).
+ *
+ * @param tasks  - Flat array of agent tasks (validated via {@link validateAgentTaskTree}).
+ * @param options - Executor, event sink, and optional cancel signal.
+ */
+export declare function runAgentTaskTree(tasks: AgentTask[], options: RunAgentTaskTreeOptions): void;
+export declare const agentRunnerGoalDoc: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "goal";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};

package/dist/agent/runner.js

@@ -0,0 +1 @@
+export function createCancelSignal(){return{cancelled:!1}}function l(e){const n=new Map;for(const t of e){const r=t.parent,a=n.get(r);if(a)a.push(t);else n.set(r,[t])}return n}function s(e,n){e?.(n)}function i(e,n,t){const{execute:r,onEvent:a,cancelSignal:g}=t;if(g?.cancelled){s(a,{type:"agent.task_cancelled",taskId:e.id});for(const o of n.get(e.id)??[])c(o,n,a);return}s(a,{type:"agent.task_started",taskId:e.id});try{r(e);s(a,{type:"agent.task_completed",taskId:e.id})}catch(o){const d=o instanceof Error?o.message:String(o);s(a,{type:"agent.task_failed",taskId:e.id,error:d});return}for(const o of n.get(e.id)??[])i(o,n,t)}function c(e,n,t){s(t,{type:"agent.task_cancelled",taskId:e.id});for(const r of n.get(e.id)??[])c(r,n,t)}export function runAgentTaskTree(e,n){const t=l(e),r=t.get(void 0)??[];for(const a of r)i(a,t,n)}export const agentRunnerGoalDoc={id:"docs.tech.agent.runner.goal",title:"Agent runner \u2014 goal",summary:"Synchronous depth-first agent task-tree executor with cancel propagation.",kind:"goal",visibility:"public",route:"/docs/tech/agent/runner/goal",tags:["agent","runner","task-tree"],body:"# Agent runner\n\nThe agent runner walks a flat list of `AgentTask` records as a depth-first tree,\nexecuting parent tasks before their children. It emits four lifecycle events:\n`agent.task_started`, `agent.task_completed`, `agent.task_failed`, and\n`agent.task_cancelled`. Cancellation propagates to all remaining descendants."};

package/dist/agent/spec.d.ts

@@ -0,0 +1,264 @@
+import type { DataViewRef, FormRef, PresentationRef } from '../features/index.js';
+import type { KnowledgeCategory } from '../knowledge/spec.js';
+import type { OwnerShipMeta } from '../ownership.js';
+import type { PolicyRef } from '../policy/spec.js';
+import type { AgentRuntimeAdapterKey } from '../runtime-adapters.js';
+import { type AgentProtocolConfigV1 } from './protocol/application.js';
+export type { AgentRuntimeAdapterKey } from '../runtime-adapters.js';
+export declare const AgentOperationsAsToolsDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+export declare const AgentSubagentsDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+export declare const AgentMemoryToolsDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+export declare const AgentWorkflowIntegrationDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+/**
+ * Metadata for an agent specification.
+ */
+export type AgentMeta = OwnerShipMeta;
+export interface AgentRuntimeCapabilities {
+    /** Optional external adapter availability map for runtime interoperability. */
+    adapters?: Partial<Record<AgentRuntimeAdapterKey, boolean>>;
+    /** Whether the agent should persist checkpoints for replay/resume. */
+    checkpointing?: boolean;
+    /** Whether the agent supports external suspend/resume semantics. */
+    suspendResume?: boolean;
+    /** Whether the agent can delegate approvals to external gateways. */
+    approvalGateway?: boolean;
+}
+export interface AgentRuntimePorts {
+    /** Symbolic checkpoint store adapter identifier. */
+    checkpointStore?: string;
+    /** Symbolic suspend/resume adapter identifier. */
+    suspension?: string;
+    /** Symbolic retry classifier identifier. */
+    retryClassifier?: string;
+    /** Symbolic approval gateway identifier. */
+    approvalGateway?: string;
+}
+export interface AgentRuntimeConfig {
+    capabilities?: AgentRuntimeCapabilities;
+    ports?: AgentRuntimePorts;
+}
+/**
+ * Reference to a ContractSpec operation that backs an agent tool.
+ * When set, the tool is a projection of the operation (one contract -> REST, GraphQL, MCP, agent).
+ */
+export interface OperationRef {
+    /** Operation key (e.g., "knowledge.search") */
+    key: string;
+    /** Optional specific version; defaults to latest when omitted */
+    version?: string;
+}
+/**
+ * Reference to a subagent that backs an agent tool.
+ * When set, the tool delegates to the subagent; mutually exclusive with operationRef and manual handler.
+ */
+export interface SubagentRef {
+    /** Subagent identifier (resolved from subagent registry) */
+    agentId: string;
+    /** Whether to extract summary for toModelOutput (default: true) */
+    toModelSummary?: boolean;
+    /**
+     * Pass full conversation history to subagent (opt-in).
+     * Defeats context isolation; use sparingly. Requires subagent to support generate({ messages }).
+     * Streaming is disabled when history is passed.
+     */
+    passConversationHistory?: boolean;
+}
+/**
+ * Configuration for a tool that an agent can use.
+ */
+export interface AgentToolConfig {
+    /** Tool name (unique within the agent) */
+    name: string;
+    /**
+     * Reference to a ContractSpec operation. When set, the tool is backed by the operation:
+     * schema and handler are derived from the operation; no manual handler needed.
+     */
+    operationRef?: OperationRef;
+    /**
+     * Reference to a subagent. When set, the tool delegates to the subagent.
+     * Mutually exclusive with operationRef; requires subagentRegistry in agent config.
+     */
+    subagentRef?: SubagentRef;
+    /** Human-readable description for the LLM */
+    description?: string;
+    /** JSON Schema fragment for tool parameters (fallback when no operationRef) */
+    schema?: Record<string, unknown>;
+    /** Optional cooldown in milliseconds between invocations */
+    cooldownMs?: number;
+    /** Maximum execution time before timeout */
+    timeoutMs?: number;
+    /** Whether the tool can be executed without human approval (AI SDK needsApproval = !automationSafe) */
+    automationSafe?: boolean;
+    /** Explicit approval requirement (overrides automationSafe) */
+    requiresApproval?: boolean;
+    /** Optional policy guard that must evaluate to allow the tool call */
+    policy?: PolicyRef;
+    /**
+     * When set, wrap raw output as { presentationKey, data } for ToolResultRenderer.
+     * At most one of outputPresentation, outputForm, outputDataView per tool.
+     */
+    outputPresentation?: PresentationRef;
+    /**
+     * When set, wrap raw output as { formKey, defaultValues } for ToolResultRenderer.
+     * At most one of outputPresentation, outputForm, outputDataView per tool.
+     */
+    outputForm?: FormRef;
+    /**
+     * When set, wrap raw output as { dataViewKey, items } for ToolResultRenderer.
+     * At most one of outputPresentation, outputForm, outputDataView per tool.
+     */
+    outputDataView?: DataViewRef;
+}
+/**
+ * Reference to a knowledge space that the agent can access.
+ */
+export interface AgentKnowledgeRef {
+    /** Knowledge space key */
+    key: string;
+    /** Optional specific version */
+    version?: number;
+    /** Filter by knowledge category */
+    category?: KnowledgeCategory;
+    /** Whether the knowledge is required (static injection) or optional (dynamic RAG) */
+    required?: boolean;
+    /** Additional instructions appended when the space is available */
+    instructions?: string;
+}
+/**
+ * Memory configuration for agent session persistence.
+ */
+export interface AgentMemoryConfig {
+    /** Maximum entries to keep in memory */
+    maxEntries?: number;
+    /** Time-to-live in minutes */
+    ttlMinutes?: number;
+    /** Number of messages before triggering summarization */
+    summaryTrigger?: number;
+    /** Whether to persist to long-term storage */
+    persistLongTerm?: boolean;
+}
+/**
+ * Memory tools config - model-accessible CRUD (Anthropic memory, custom).
+ * Distinct from AgentMemoryConfig (session summarization).
+ *
+ * @see https://ai-sdk.dev/docs/agents/memory
+ */
+export interface AgentMemoryToolsConfig {
+    /** Provider: anthropic uses memory_20250818; custom uses operationRef. */
+    provider: 'anthropic' | 'custom';
+    /** Storage adapter key when using knowledge-backed storage (e.g. ephemeral space) */
+    storageAdapter?: string;
+    /** Ephemeral KnowledgeSpaceSpec key when using knowledge-backed storage */
+    spaceKey?: string;
+}
+/**
+ * Confidence policy for agent responses.
+ */
+export interface AgentConfidencePolicy {
+    /** Minimum acceptable confidence before escalation. Defaults to 0.7 */
+    min?: number;
+    /** Default value used when provider does not report confidence */
+    default?: number;
+}
+/**
+ * Escalation policy for handling uncertain or failed agent responses.
+ */
+export interface AgentEscalationPolicy {
+    /** Auto escalate when confidence < threshold */
+    confidenceThreshold?: number;
+    /** Escalate when a tool throws irrecoverable errors */
+    onToolFailure?: boolean;
+    /** Escalate when iteration budget exceeded */
+    onTimeout?: boolean;
+    /** Optional human approval workflow ID */
+    approvalWorkflow?: string;
+}
+/**
+ * Combined policy configuration for an agent.
+ */
+export interface AgentPolicy {
+    confidence?: AgentConfidencePolicy;
+    escalation?: AgentEscalationPolicy;
+    /** Feature flags to apply to this agent */
+    flags?: string[];
+}
+/**
+ * Complete specification for a ContractSpec agent.
+ */
+export interface AgentSpec {
+    meta: AgentMeta;
+    /** System instructions for the agent */
+    instructions: string;
+    /** Human-readable description */
+    description?: string;
+    /** Tags for categorization */
+    tags?: string[];
+    /** Default locale for the agent (e.g., "en", "fr"). Falls back to "en" if unset. */
+    locale?: string;
+    /** Tools the agent can use */
+    tools: AgentToolConfig[];
+    /** Memory/session configuration */
+    memory?: AgentMemoryConfig;
+    /** Memory tools (model-accessible CRUD) - Anthropic or custom operation-backed */
+    memoryTools?: AgentMemoryToolsConfig;
+    /** Knowledge spaces the agent can access */
+    knowledge?: AgentKnowledgeRef[];
+    /** Policy configuration */
+    policy?: AgentPolicy;
+    /** Runtime adapter and portability config. */
+    runtime?: AgentRuntimeConfig;
+    /** Optional durable Plan–Act–Reflect protocol; legacy agents remain valid. */
+    protocol?: AgentProtocolConfigV1;
+    /** Opaque CommunicationOS profile reference; never a routing authority. */
+    communicationProfileRef?: string;
+    /** Maximum steps per generation (defaults to 10) */
+    maxSteps?: number;
+}
+/**
+ * Define and validate an agent specification.
+ *
+ * @param spec - The agent specification
+ * @returns The frozen, validated specification
+ * @throws Error if the specification is invalid
+ */
+export declare function defineAgent(spec: AgentSpec): AgentSpec;
+/**
+ * Generate a unique key for an agent spec.
+ */
+export declare function agentKey(meta: AgentMeta): string;

package/dist/agent/spec.js

@@ -0,0 +1,10 @@
+import{agentProtocolConfigV1Schema as r}from"./protocol/application.js";export const AgentOperationsAsToolsDocBlock={id:"docs.tech.agent.operations-as-tools",title:"Operations as tools",summary:"Reference ContractSpec operations as agent tools. One contract to many surfaces.",kind:"reference",visibility:"public",route:"/docs/tech/agent/operations-as-tools",tags:["agent","tools","operations"],body:"# Operations as tools\n\nReference ContractSpec operations in `AgentSpec.tools` with `operationRef` to reuse schemas, handlers, and output bindings across REST, GraphQL, MCP, and agent execution.\n"};export const AgentSubagentsDocBlock={id:"docs.tech.agent.subagents",title:"Subagents",summary:"Delegate tasks to subagents with streaming and isolated context.",kind:"reference",visibility:"public",route:"/docs/tech/agent/subagents",tags:["agent","subagents","delegation"],body:`# Subagents
+
+Subagents let a primary agent delegate bounded work to worker agents while keeping orchestration, summaries, and approval policy in the parent flow.
+`};export const AgentMemoryToolsDocBlock={id:"docs.tech.agent.memory-tools",title:"Memory tools",summary:"Governed memory proposals with legacy direct-store compatibility.",kind:"reference",visibility:"public",route:"/docs/tech/agent/memory-tools",tags:["agent","memory","tools"],body:`# Memory tools
+
+Protocol V1 memory tools create provenance-bound proposals only. PersonalOS or CompanyOS must independently bind consent, policy, retention, authority, revision, and evidence before committing a mutation. The legacy direct-store adapter remains available only for non-Protocol-V1 agents and does not establish governed production memory.
+`};export const AgentWorkflowIntegrationDocBlock={id:"docs.tech.agent.workflow-integration",title:"Workflow-agent integration",summary:"Patterns for orchestrator-worker, workflow steps, and evaluator loops.",kind:"reference",visibility:"public",route:"/docs/tech/agent/workflow-integration",tags:["agent","workflow","orchestrator"],body:`# Workflow-agent integration
+
+Agents can act as workflow workers, orchestrators, or evaluators. Contract-backed operations keep those integrations explicit and replayable.
+`};export function defineAgent(e){if(!e.meta?.key)throw Error("Agent key is required");if(typeof e.meta.version!=="string")throw Error(`Agent ${e.meta.key} is missing a string version`);if(!e.instructions?.trim())throw Error(`Agent ${e.meta.key} requires instructions`);if(!e.tools?.length)throw Error(`Agent ${e.meta.key} must expose at least one tool`);for(const[t,o]of Object.entries(e.runtime?.ports??{}))if(o!==void 0&&o.trim().length===0)throw Error(`Agent ${e.meta.key} has invalid runtime config: port "${t}" must not be empty`);const n=new Set;for(const t of e.tools){if(n.has(t.name))throw Error(`Agent ${e.meta.key} has duplicate tool name: ${t.name}`);n.add(t.name);if(t.subagentRef&&t.operationRef)throw Error(`Agent ${e.meta.key} tool "${t.name}" cannot have both subagentRef and operationRef. Use one.`);if([t.outputPresentation,t.outputForm,t.outputDataView].filter(Boolean).length>1)throw Error(`Agent ${e.meta.key} tool "${t.name}" has multiple output refs (outputPresentation, outputForm, outputDataView). Use at most one.`)}if(e.communicationProfileRef!==void 0&&e.communicationProfileRef.trim().length===0)throw Error(`Agent ${e.meta.key} has invalid communicationProfileRef: it must not be empty`);if(e.protocol){const t=r.safeParse(e.protocol);if(!t.success)throw Error(`Agent ${e.meta.key} has invalid protocol config: ${t.error.issues[0]?.message??"unsupported protocol version"}`);for(const o of e.tools)if(o.subagentRef?.passConversationHistory)throw Error(`Agent ${e.meta.key} protocol V1 forbids full-history subagent delegation`)}return Object.freeze(e)}export function agentKey(e){return`${e.key}.v${e.version}`}