@lssm/lib.contracts-spec 17.3.2

package/dist/node/adaptive-shell/index.js

@@ -0,0 +1 @@
+export{defineAdaptiveShellResolution,defineAdaptiveShellSpec,validateAdaptiveShellResolution,validateAdaptiveShellSpec}from"./validation.js";

package/dist/node/adaptive-shell/validation.js

@@ -0,0 +1 @@
+const c=["rolemorph-first","personalization-after-policy","fail-closed-missing-rolemorph","deny-hidden-actions","workspace-intent-preserved","explain-every-adaptation","graph-router-owned-drilldown","deterministic-output"];export function validateAdaptiveShellSpec(o){const i=[];if(!o.id.trim())i.push(a("missing_spec_id","Adaptive shell id is required."));if(!o.version.trim())i.push(a("missing_version","Adaptive shell version is required."));if(!o.surfaceId.trim())i.push(a("missing_surface_id","Adaptive shell surfaceId is required."));if(!o.title.trim())i.push(a("missing_title","Adaptive shell title is required."));if(o.regions.length===0)i.push(a("missing_regions","Adaptive shell requires at least one region."));if(o.navigation.length===0)i.push(a("missing_navigation","Adaptive shell requires at least one navigation node."));if(o.layoutVariants.length===0)i.push(a("missing_layout_variants","Adaptive shell requires at least one layout variant."));if(o.signals.length===0)i.push(a("missing_signals","Adaptive shell requires at least one adaptation signal."));const s=g(o.regions,"region","duplicate_region_id",i),r=g(o.signals,"signal","duplicate_signal_id",i);g(o.layoutVariants,"layout variant","duplicate_layout_variant_id",i);const d=g(o.navigation,"navigation node","duplicate_navigation_node_id",i);for(const n of o.regions)for(const l of n.onlyWhenSignalRefs??[])if(!r.has(l))i.push(a("unresolved_region_signal_ref",`Region ${n.id} references missing signal ${l}.`,n.id));for(const n of o.navigation){if(!s.has(n.regionRef))i.push(a("unresolved_navigation_region_ref",`Navigation node ${n.id} references missing region ${n.regionRef}.`,n.id));if(n.kind==="route"&&!n.href)i.push(a("missing_route_href",`Route navigation node ${n.id} requires href.`,n.id));if(n.kind==="action"&&!n.actionId)i.push(a("missing_action_id",`Action navigation node ${n.id} requires actionId.`,n.id));if(n.kind==="graph-node"&&!n.graphNodeRef)i.push(a("missing_graph_node_ref",`Graph navigation node ${n.id} requires graphNodeRef.`,n.id))}for(const n of o.navigation)if(n.parentId&&!d.has(n.parentId))i.push(a("unresolved_navigation_parent_ref",`Navigation node ${n.id} references missing parent ${n.parentId}.`,n.id));const t=g(o.breadcrumbs??[],"breadcrumb","duplicate_breadcrumb_id",i);for(const n of o.breadcrumbs??[])if(!d.has(n.navigationNodeRef))i.push(a("unresolved_breadcrumb_navigation_ref",`Breadcrumb ${n.id} references missing navigation node ${n.navigationNodeRef}.`,n.id));for(const n of o.layoutVariants){if(n.regionRefs.length===0)i.push(a("missing_layout_regions",`Layout variant ${n.id} requires at least one region.`,n.id));for(const l of n.regionRefs)if(!s.has(l))i.push(a("unresolved_layout_region_ref",`Layout variant ${n.id} references missing region ${l}.`,n.id))}const p=new Set(o.invariants.filter((n)=>n.required).map((n)=>n.kind));for(const n of c)if(!p.has(n))i.push(a("missing_required_invariant",`Adaptive shell requires invariant ${n}.`,n));if(o.compatibility?.classification==="breaking-change"&&!o.compatibility.migrationRefs?.length)i.push(a("missing_breaking_migration_refs","Breaking adaptive shell compatibility changes require migration refs."));return{ok:i.every((n)=>n.level!=="error"),diagnostics:i}}export function validateAdaptiveShellResolution(o,i){const s=[],r=validateAdaptiveShellSpec(o);s.push(...r.diagnostics);if(i.specId!==o.id)s.push(a("resolution_spec_mismatch",`Resolution specId ${i.specId} does not match spec ${o.id}.`,i.specId));if(i.surfaceId!==o.surfaceId)s.push(a("resolution_surface_mismatch",`Resolution surfaceId ${i.surfaceId} does not match spec ${o.surfaceId}.`,i.surfaceId));if(!i.workspaceIntentRef.trim())s.push(a("missing_workspace_intent_ref","Adaptive shell resolution must preserve workspace intent."));if(!i.roleMorphResolutionRef)s.push(a("missing_rolemorph_resolution_ref","Adaptive shell resolution must fail closed without a RoleMorph resolution ref."));const d=new Set(o.regions.map((e)=>e.id)),t=new Set(o.navigation.map((e)=>e.id)),p=new Set((o.breadcrumbs??[]).map((e)=>e.id)),n=new Set(o.layoutVariants.map((e)=>e.id)),l=new Set(o.signals.map((e)=>e.id)),f=new Set(i.explanations.map((e)=>e.id));if(!n.has(i.layoutVariantRef))s.push(a("unresolved_resolution_layout_ref",`Resolution references missing layout variant ${i.layoutVariantRef}.`,i.layoutVariantRef));for(const e of i.regions){if(!d.has(e.regionRef))s.push(a("unresolved_resolution_region_ref",`Resolution references missing region ${e.regionRef}.`,e.regionRef));if(e.explanationRef&&!f.has(e.explanationRef))s.push(a("unresolved_region_explanation_ref",`Resolved region ${e.regionRef} references missing explanation ${e.explanationRef}.`,e.regionRef))}for(const e of i.navigation){if(!t.has(e.navigationNodeRef))s.push(a("unresolved_resolution_navigation_ref",`Resolution references missing navigation node ${e.navigationNodeRef}.`,e.navigationNodeRef));if(e.visible&&e.disabled&&!e.suppressionReason)s.push(a("missing_disabled_navigation_reason",`Disabled navigation node ${e.navigationNodeRef} requires suppressionReason.`,e.navigationNodeRef));if(e.safetyLevel!=="safe"&&!e.suppressionReason)s.push(a("missing_unsafe_navigation_reason",`Unsafe navigation node ${e.navigationNodeRef} requires suppressionReason.`,e.navigationNodeRef));if(e.explanationRef&&!f.has(e.explanationRef))s.push(a("unresolved_navigation_explanation_ref",`Resolved navigation node ${e.navigationNodeRef} references missing explanation ${e.explanationRef}.`,e.navigationNodeRef))}for(const e of i.breadcrumbs){if(!p.has(e.breadcrumbRef))s.push(a("unresolved_resolution_breadcrumb_ref",`Resolution references missing breadcrumb ${e.breadcrumbRef}.`,e.breadcrumbRef));if(!t.has(e.navigationNodeRef))s.push(a("unresolved_resolution_breadcrumb_navigation_ref",`Resolved breadcrumb ${e.breadcrumbRef} references missing navigation node ${e.navigationNodeRef}.`,e.breadcrumbRef))}for(const e of i.actions??[]){if(e.navigationNodeRef&&!t.has(e.navigationNodeRef))s.push(a("unresolved_action_navigation_ref",`Resolved action ${e.actionId} references missing navigation node ${e.navigationNodeRef}.`,e.actionId));if(e.safetyLevel!=="safe"&&e.available)s.push(a("unsafe_action_available",`Unsafe action ${e.actionId} cannot be available.`,e.actionId));if(!f.has(e.explanationRef))s.push(a("unresolved_action_explanation_ref",`Resolved action ${e.actionId} references missing explanation ${e.explanationRef}.`,e.actionId))}for(const e of i.adaptations){if(!l.has(e.signalRef))s.push(a("unresolved_adaptation_signal_ref",`Adaptation ${e.id} references missing signal ${e.signalRef}.`,e.id));if(!e.evidenceRefs.length)s.push(a("missing_adaptation_evidence_refs",`Adaptation ${e.id} requires evidence refs.`,e.id));if(!e.reason.trim())s.push(a("missing_adaptation_reason",`Adaptation ${e.id} requires a reason.`,e.id));if(!f.has(e.explanationRef))s.push(a("unresolved_adaptation_explanation_ref",`Adaptation ${e.id} references missing explanation ${e.explanationRef}.`,e.id));if(e.safetyLevel!=="safe"&&e.applied)s.push(a("unsafe_adaptation_applied",`Unsafe adaptation ${e.id} cannot be applied.`,e.id))}for(const e of i.graphTargets??[]){if(e.navigationNodeRef&&!t.has(e.navigationNodeRef))s.push(a("unresolved_graph_navigation_ref",`Graph target ${e.id} references missing navigation node ${e.navigationNodeRef}.`,e.id));if(!e.routerOwned)s.push(a("graph_drilldown_not_router_owned",`Graph target ${e.id} must keep drilldown routing owned by the app/router layer.`,e.id));if(!f.has(e.explanationRef))s.push(a("unresolved_graph_explanation_ref",`Graph target ${e.id} references missing explanation ${e.explanationRef}.`,e.id))}const u=new Set(o.invariants.filter((e)=>e.required).map((e)=>e.kind)),v=new Set(i.invariants.map((e)=>e.kind));for(const e of u)if(!v.has(e))s.push(a("missing_resolution_invariant_status",`Resolution must report invariant status for ${e}.`,e));return{ok:s.every((e)=>e.level!=="error"),diagnostics:s}}export function defineAdaptiveShellSpec(o){const i=validateAdaptiveShellSpec(o);if(!i.ok)throw Error(`Invalid AdaptiveShellSpec ${o.id}: ${i.diagnostics.map((s)=>s.message).join("; ")}`);return o}export function defineAdaptiveShellResolution(o,i){const s=validateAdaptiveShellResolution(o,i);if(!s.ok)throw Error(`Invalid AdaptiveShellResolution ${i.specId}: ${s.diagnostics.map((r)=>r.message).join("; ")}`);return i}function g(o,i,s,r){const d=new Set;for(const t of o){if(!t.id.trim()){r.push(a(`missing_${i.replaceAll(" ","_")}_id`,`Adaptive shell ${i} id is required.`));continue}if(d.has(t.id))r.push(a(s,`Duplicate shell ${i} id ${t.id}.`,t.id));d.add(t.id)}return d}function a(o,i,s){return{code:o,level:"error",message:i,refId:s}}

package/dist/node/adoption-catalog/index.js

@@ -0,0 +1 @@
+import{sha256Hex as y}from"@lssm/lib.crypto-utils";import{z as a}from"zod";const t=a.string().trim().min(1),u=a.string().url(),f=a.string().regex(/^sha256:[a-f0-9]{64}$/);export const AdoptionCatalogFamilySchema=a.enum(["contracts","integrations","runtime","sharedLibs","solutions","ui"]),AdoptionCatalogPackageKindV2Schema=a.enum(["library","integration","module","bundle","app","example","tool","agent-pack"]),AdoptionCatalogPackageStatusSchema=a.enum(["active","deprecated","removed","internal"]),AdoptionCatalogCapabilityStatusSchema=a.enum(["active","alias","merged","deprecated","internal"]),AdoptionCatalogStabilitySchema=a.enum(["experimental","beta","stable","deprecated"]),AdoptionCatalogAdoptionModeSchema=a.enum(["adoptable","reference-only","operator-only"]),AdoptionCatalogAvailabilitySchema=a.enum(["workspace-available","published","qualified-adoptable"]),AdoptionCatalogImportSchema=a.object({from:t,symbols:a.array(t).default([]),note:t.optional()}),AdoptionCatalogDocumentationSchema=a.object({title:t,url:u,kind:a.enum(["readme","reference","guide","migration","example"]).default("reference")}),AdoptionCatalogRegistryProvenanceSchema=a.object({registry:a.enum(["npm","github-packages","other"]),registryUrl:u,distTag:t.default("latest"),integrity:t.optional(),publishedAt:a.string().datetime().optional(),verifiedAt:a.string().datetime()}),AdoptionCatalogPackageV2Schema=a.object({name:t,version:t,description:t,license:t.optional(),family:AdoptionCatalogFamilySchema,kind:AdoptionCatalogPackageKindV2Schema,status:AdoptionCatalogPackageStatusSchema,adoptionMode:AdoptionCatalogAdoptionModeSchema,availability:AdoptionCatalogAvailabilitySchema.optional(),installable:a.boolean(),stability:AdoptionCatalogStabilitySchema,exports:a.array(t),dependencies:a.record(a.string(),t).default({}),peerDependencies:a.record(a.string(),t).default({}),platforms:a.array(t).default([]),runtimes:a.array(t).default([]),documentation:a.array(AdoptionCatalogDocumentationSchema).min(1),examples:a.array(AdoptionCatalogDocumentationSchema).default([]),replacements:a.array(t).default([]),registry:a.array(AdoptionCatalogRegistryProvenanceSchema).default([]),nonAdoptableRationale:t.optional()}).superRefine((e,o)=>{if(e.adoptionMode!=="adoptable"&&!e.nonAdoptableRationale)o.addIssue({code:"custom",message:"Reference-only and operator-only packages require nonAdoptableRationale.",path:["nonAdoptableRationale"]});if(e.status==="active"&&!e.installable)o.addIssue({code:"custom",message:"Active packages must be installable.",path:["installable"]});const r=e.availability;if(r==="workspace-available"&&e.registry.length)o.addIssue({code:"custom",message:"Workspace-only packages cannot claim registry provenance.",path:["registry"]});if(r!==void 0&&r!=="workspace-available"&&!e.registry.length)o.addIssue({code:"custom",message:"Published packages require registry provenance.",path:["registry"]});if(r==="qualified-adoptable"&&(e.adoptionMode!=="adoptable"||e.registry.some((i)=>!i.integrity)))o.addIssue({code:"custom",message:"Qualified adoption requires adoptable policy and integrity-backed registry provenance.",path:["availability"]})}),AdoptionCatalogCapabilityV2Schema=a.object({id:t,packageName:t,title:t,description:t,status:AdoptionCatalogCapabilityStatusSchema,useCases:a.array(t).min(1),aliases:a.array(t).default([]),pythonEquivalents:a.array(t).default([]),canonicalImports:a.array(AdoptionCatalogImportSchema).default([]),constraints:a.object({platforms:a.array(t).default([]),runtimes:a.array(t).default([]),avoidWhen:a.array(t).default([]),requires:a.array(t).default([])}).default({platforms:[],runtimes:[],avoidWhen:[],requires:[]}),alternatives:a.array(t).default([]),relationships:a.array(a.object({type:a.enum(["requires","complements","replaces","supersedes"]),targetId:t})).default([]),resolutionPriority:a.number().int().default(50)}),AdoptionCatalogMigrationV2Schema=a.object({id:t,packageName:t.optional(),from:t,to:t,deterministicFixes:a.array(a.object({id:t,description:t,codemod:t})).default([]),assistedSteps:a.array(t).default([]),manualSteps:a.array(t).default([]),verificationCommands:a.array(t).default([]),deprecations:a.array(t).default([])}),AdoptionCatalogLegacyEntrySchema=a.object({id:t,source:a.enum(["contractspec","ecosystem"]),packageRef:t,family:AdoptionCatalogFamilySchema,packageKind:a.enum(["primitive","adapter","module","bundle","app","example"]),title:t,description:t,capabilityTags:a.array(t),preferredUseCases:a.array(t),avoidWhen:a.array(t).optional(),platforms:a.array(t).optional(),runtimes:a.array(t).optional(),replacementImportHints:a.array(a.object({from:t,to:t,note:t.optional()})).optional(),resolutionPriority:a.number().int(),availability:AdoptionCatalogAvailabilitySchema.optional()}),AdoptionCatalogSourceEvidenceSchema=a.object({kind:a.enum(["package-manifest","npm-registry","github-packages","release-manifest","consumer-override"]),ref:t,digest:f.optional(),observedAt:a.string().datetime()});const h=a.object({version:a.literal(2),catalogVersion:t,generatedAt:a.string().datetime(),contentHash:f,sourceEvidence:a.array(AdoptionCatalogSourceEvidenceSchema).min(1),packages:a.array(AdoptionCatalogPackageV2Schema),capabilities:a.array(AdoptionCatalogCapabilityV2Schema),migrations:a.array(AdoptionCatalogMigrationV2Schema),entries:a.array(AdoptionCatalogLegacyEntrySchema)});export const AdoptionCatalogV2Schema=h.superRefine((e,o)=>{g(e.packages,"name","packages",o);g(e.capabilities,"id","capabilities",o);g(e.migrations,"id","migrations",o);const r=new Set(e.packages.map((n)=>n.name)),i=new Set(e.capabilities.map((n)=>n.id)),s=new Set(e.capabilities.map((n)=>n.packageName));e.packages.forEach((n,p)=>{if(n.adoptionMode==="adoptable"&&!s.has(n.name))o.addIssue({code:"custom",message:"Adoptable packages require at least one capability.",path:["packages",p,"adoptionMode"]});n.replacements.forEach((l,d)=>{if(!r.has(l))o.addIssue({code:"custom",message:`Unknown replacement package ${l}.`,path:["packages",p,"replacements",d]})})});e.capabilities.forEach((n,p)=>{if(!r.has(n.packageName))o.addIssue({code:"custom",message:`Unknown owning package ${n.packageName}.`,path:["capabilities",p,"packageName"]});n.relationships.forEach((l,d)=>{if(!i.has(l.targetId))o.addIssue({code:"custom",message:`Unknown related capability ${l.targetId}.`,path:["capabilities",p,"relationships",d,"targetId"]})})});e.migrations.forEach((n,p)=>{if(n.packageName&&!r.has(n.packageName))o.addIssue({code:"custom",message:`Unknown migration package ${n.packageName}.`,path:["migrations",p,"packageName"]})});const c=computeAdoptionCatalogContentHash(e);if(e.contentHash!==c)o.addIssue({code:"custom",message:`Catalog content hash mismatch; expected ${c}.`,path:["contentHash"]})});export function createAdoptionCatalogV2Document(e){const o={version:2,catalogVersion:e.catalogVersion,generatedAt:e.generatedAt??new Date().toISOString(),contentHash:`sha256:${"0".repeat(64)}`,sourceEvidence:e.sourceEvidence,packages:e.packages,capabilities:e.capabilities,migrations:e.migrations??[],entries:projectAdoptionCatalogV1Entries(e.packages,e.capabilities)};o.contentHash=computeAdoptionCatalogContentHash(o);return AdoptionCatalogV2Schema.parse(o)}export function parseAdoptionCatalogV2(e){return AdoptionCatalogV2Schema.parse(e)}export function computeAdoptionCatalogContentHash(e){const o={version:e.version,catalogVersion:e.catalogVersion,sourceEvidence:e.sourceEvidence.map(({observedAt:r,...i})=>i),packages:e.packages.map((r)=>({...r,registry:r.registry.map(({verifiedAt:i,...s})=>s)})),capabilities:e.capabilities,migrations:e.migrations,entries:e.entries};return`sha256:${y(A(o))}`}export function projectAdoptionCatalogV1Entries(e,o){const r=new Map(e.map((i)=>[i.name,i]));return o.filter((i)=>i.status!=="internal").flatMap((i)=>{const s=r.get(i.packageName);if(!s)return[];return[{id:i.id,source:"contractspec",packageRef:s.name,family:s.family,packageKind:b(s.kind),title:i.title,description:i.description,capabilityTags:[...i.aliases,...i.pythonEquivalents],preferredUseCases:i.useCases,avoidWhen:i.constraints.avoidWhen,platforms:i.constraints.platforms.length?i.constraints.platforms:s.platforms,runtimes:i.constraints.runtimes.length?i.constraints.runtimes:s.runtimes,replacementImportHints:i.canonicalImports.map((c)=>({from:s.name,to:c.from,note:c.note})),resolutionPriority:i.resolutionPriority,availability:s.availability??"workspace-available"}]})}function b(e){if(e==="integration")return"adapter";if(e==="module"||e==="bundle"||e==="app")return e;if(e==="example")return"example";return"primitive"}function g(e,o,r,i){const s=new Set;e.forEach((c,n)=>{const p=c[o];if(s.has(p))i.addIssue({code:"custom",message:`Duplicate ${String(o)} ${p}.`,path:[r,n,String(o)]});s.add(p)})}function A(e){return JSON.stringify(m(e))}function m(e){if(Array.isArray(e))return e.map(m);if(e&&typeof e==="object")return Object.fromEntries(Object.entries(e).sort(([o],[r])=>o.localeCompare(r)).map(([o,r])=>[o,m(r)]));return e}

package/dist/node/agent/agent.feature.js

@@ -0,0 +1,4 @@
+import{defineFeature as e}from"../features/index.js";import{AGENT_DOMAIN as t,AGENT_OWNERS as n,AGENT_STABILITY as a,AGENT_TAGS as o}from"./constants.js";export const AgentExecutionDocBlock={id:"docs.tech.agent.execution",title:"Agent execution",summary:"Background agent execution, approvals, and artifacts.",kind:"reference",visibility:"public",route:"/docs/tech/agent/execution",tags:["agent","execution"],body:`# Agent execution
+
+Defines the core operations, events, and UI surfaces for background agent runs with auditability and approvals.
+`},AgentFeature=e({meta:{key:"platform.agent",version:"1.0.0",title:"Agent Execution",description:"Run, cancel, and approve AI agent executions with full audit trail",domain:t,owners:n,tags:[...o],stability:a},operations:[{key:"agent.run",version:"1.0.0"},{key:"agent.cancel",version:"1.0.0"},{key:"agent.approvals",version:"1.0.0"},{key:"agent.status",version:"1.0.0"},{key:"agent.artifacts",version:"1.0.0"},{key:"agent.task.run",version:"1.0.0"},{key:"agent.task.cancel",version:"1.0.0"},{key:"agent.task.tree",version:"1.0.0"},{key:"agent.task.assign",version:"1.0.0"}],events:[{key:"agent.run.started",version:"1.0.0"},{key:"agent.run.completed",version:"1.0.0"},{key:"agent.run.failed",version:"1.0.0"},{key:"agent.approval.requested",version:"1.0.0"}],presentations:[{key:"agent.run.audit",version:"1.0.0"}],capabilities:{provides:[{key:"agent.execution",version:"1.0.0"}]},dataViews:[{key:"agent.run.index",version:"1.0.0"}],forms:[{key:"agent.run.form",version:"1.0.0"}]});

package/dist/node/agent/capabilities/agentExecution.capability.js

@@ -0,0 +1 @@
+import{defineCapability as e}from"../../capabilities/index.js";import{docId as t}from"../../docs/registry.js";import{AGENT_DOMAIN as n,AGENT_OWNERS as r,AGENT_STABILITY as a,AGENT_TAGS as i}from"../constants.js";export const AgentExecutionCapability=e({meta:{key:"agent.execution",version:"1.0.0",kind:"integration",title:"Agent Execution",description:"Background agent execution, approvals, and artifacts.",domain:n,owners:r,tags:[...i,"execution"],stability:a,docId:[t("docs.tech.agent.execution")]},provides:[{surface:"operation",key:"agent.run",version:"1.0.0",description:"Submit an agent run."},{surface:"operation",key:"agent.status",version:"1.0.0",description:"Query agent run status."},{surface:"operation",key:"agent.cancel",version:"1.0.0",description:"Cancel an agent run."},{surface:"operation",key:"agent.artifacts",version:"1.0.0",description:"List agent artifacts."},{surface:"operation",key:"agent.approvals",version:"1.0.0",description:"Resolve an agent approval request."},{surface:"event",key:"agent.run.started",version:"1.0.0",description:"Agent run started event."},{surface:"event",key:"agent.run.completed",version:"1.0.0",description:"Agent run completed event."},{surface:"event",key:"agent.run.failed",version:"1.0.0",description:"Agent run failed event."},{surface:"event",key:"agent.approval.requested",version:"1.0.0",description:"Approval requested event."},{surface:"presentation",key:"agent.run.audit",version:"1.0.0",description:"Audit presentation for agent runs."}]});

package/dist/node/agent/capabilities/index.js

@@ -0,0 +1 @@
+export*from"./agentExecution.capability.js";

package/dist/node/agent/commands/agentApprovals.command.js

@@ -0,0 +1,4 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{docId as o}from"../../docs/registry.js";import{defineCommand as p}from"../../operations/index.js";import{AGENT_DOMAIN as a,AGENT_OWNERS as n,AGENT_STABILITY as r,AGENT_TAGS as s}from"../constants.js";const i=new t({name:"AgentApprovalsInput",fields:{runId:{type:e.ID(),isOptional:!1},action:{type:e.String_unsecure(),isOptional:!1},comment:{type:e.String_unsecure(),isOptional:!0},approverId:{type:e.ID(),isOptional:!0}}}),l=new t({name:"AgentApprovalsOutput",fields:{approvalId:{type:e.ID(),isOptional:!1},status:{type:e.String_unsecure(),isOptional:!1},resolvedAt:{type:e.DateTime(),isOptional:!0}}});export const AgentApprovalsDocBlock={id:"docs.tech.agent.approvals",title:"Agent approvals",summary:"Resolve an agent approval request.",kind:"reference",visibility:"public",route:"/docs/tech/agent/approvals",tags:["agent","approval"],body:`# agent.approvals
+
+Approve or reject a pending agent action.
+`},AgentApprovalsCommand=p({meta:{key:"agent.approvals",title:"Resolve Agent Approval",version:"1.0.0",description:"Approve or reject an agent step or run.",goal:"Provide governed human-in-the-loop control for risky steps.",context:"Used by reviewers to approve or reject agent actions.",domain:a,owners:n,tags:[...s,"approval"],stability:r,docId:[o("docs.tech.agent.approvals")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:i,output:l},policy:{auth:"admin",pii:[]}});

package/dist/node/agent/commands/agentCancel.command.js

@@ -0,0 +1,4 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{docId as n}from"../../docs/registry.js";import{defineCommand as a}from"../../operations/index.js";import{AGENT_DOMAIN as c,AGENT_OWNERS as o,AGENT_STABILITY as i,AGENT_TAGS as l}from"../constants.js";const r=new t({name:"AgentCancelInput",fields:{runId:{type:e.ID(),isOptional:!1},reason:{type:e.String_unsecure(),isOptional:!0},requestedBy:{type:e.ID(),isOptional:!0}}}),s=new t({name:"AgentCancelOutput",fields:{runId:{type:e.ID(),isOptional:!1},status:{type:e.String_unsecure(),isOptional:!1},cancelledAt:{type:e.DateTime(),isOptional:!0}}});export const AgentCancelDocBlock={id:"docs.tech.agent.cancel",title:"Cancel agent run",summary:"Cancel an in-flight agent run.",kind:"reference",visibility:"public",route:"/docs/tech/agent/cancel",tags:["agent","cancel"],body:`# agent.cancel
+
+Stops an active agent run and records cancellation metadata.
+`},AgentCancelCommand=a({meta:{key:"agent.cancel",title:"Cancel Agent Run",version:"1.0.0",description:"Cancel an in-flight agent run.",goal:"Provide safe operator control to stop background agents.",context:"Used when an agent run must be halted or escalated.",domain:c,owners:o,tags:[...l,"run","cancel"],stability:i,docId:[n("docs.tech.agent.cancel")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:r,output:s},policy:{auth:"admin",pii:[]}});

package/dist/node/agent/commands/agentRun.command.js

@@ -0,0 +1,4 @@
+import{ScalarTypeEnum as t,SchemaModel as e}from"@lssm/lib.schema";import{docId as n}from"../../docs/registry.js";import{defineCommand as a}from"../../operations/index.js";import{AGENT_DOMAIN as i,AGENT_OWNERS as o,AGENT_STABILITY as u,AGENT_TAGS as r}from"../constants.js";import{AgentRunStartedEvent as s}from"../events/agentRunStarted.event.js";const p=new e({name:"AgentRunInput",fields:{agentKey:{type:t.NonEmptyString(),isOptional:!1},contextSnapshotId:{type:t.ID(),isOptional:!0},prompt:{type:t.String_unsecure(),isOptional:!0},input:{type:t.JSONObject(),isOptional:!0},mode:{type:t.String_unsecure(),isOptional:!0},priority:{type:t.Int_unsecure(),isOptional:!0},tenantId:{type:t.ID(),isOptional:!0},actorId:{type:t.ID(),isOptional:!0},metadata:{type:t.JSONObject(),isOptional:!0}}}),c=new e({name:"AgentRunOutput",fields:{runId:{type:t.ID(),isOptional:!1},status:{type:t.String_unsecure(),isOptional:!1},submittedAt:{type:t.DateTime(),isOptional:!1},contextSnapshotId:{type:t.ID(),isOptional:!0}}});export const AgentRunDocBlock={id:"docs.tech.agent.run",title:"Run agent",summary:"Submit a background agent run.",kind:"reference",visibility:"public",route:"/docs/tech/agent/run",tags:["agent","run"],body:`# agent.run
+
+Creates a new agent run with a context snapshot and execution metadata.
+`},AgentRunCommand=a({meta:{key:"agent.run",title:"Run Agent",version:"1.0.0",description:"Submit a background agent run with a context snapshot.",goal:"Start an auditable agent execution with full provenance.",context:"Used by Studio and API clients to launch background agent workflows.",domain:i,owners:o,tags:[...r,"run"],stability:u,docId:[n("docs.tech.agent.run")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:p,output:c},policy:{auth:"user",pii:["prompt"]},sideEffects:{emits:[{ref:s.meta,when:"A new agent run is created and queued."}]}});

package/dist/node/agent/commands/agentTaskOps.command.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as t,SchemaModel as e}from"@lssm/lib.schema";import{defineCommand as o,defineQuery as l}from"../../operations/index.js";import{AGENT_DOMAIN as n,AGENT_OWNERS as a,AGENT_STABILITY as s,AGENT_TAGS as i}from"../constants.js";const p=new e({name:"AgentTaskRunInput",fields:{rootTaskId:{type:t.ID(),isOptional:!1},agentRunId:{type:t.ID(),isOptional:!1}}}),r=new e({name:"AgentTaskRunOutput",fields:{taskRunId:{type:t.ID(),isOptional:!1},status:{type:t.String_unsecure(),isOptional:!1},startedAt:{type:t.DateTime(),isOptional:!1}}});export const AgentTaskRunCommand=o({meta:{key:"agent.task.run",title:"Run Agent Task Subtree",version:"1.0.0",description:"Start execution of an agent task subtree from a given root task.",goal:"Trigger depth-first execution of a task subtree within an agent run.",context:"Used by the agent runner to initiate a task tree walk.",domain:n,owners:a,tags:[...i,"task","run"],stability:s},capability:{key:"agent.execution",version:"1.0.0"},io:{input:p,output:r},policy:{auth:"user",pii:[]}});const u=new e({name:"AgentTaskCancelInput",fields:{taskId:{type:t.ID(),isOptional:!1},reason:{type:t.String_unsecure(),isOptional:!0}}}),g=new e({name:"AgentTaskCancelOutput",fields:{taskId:{type:t.ID(),isOptional:!1},cancelled:{type:t.Boolean(),isOptional:!1},cancelledAt:{type:t.DateTime(),isOptional:!0}}});export const AgentTaskCancelCommand=o({meta:{key:"agent.task.cancel",title:"Cancel Agent Task",version:"1.0.0",description:"Cancel a running agent task and propagate cancellation to all descendants.",goal:"Provide safe operator control to stop an in-progress task subtree.",context:"Cancellation propagates depth-first to all child tasks.",domain:n,owners:a,tags:[...i,"task","cancel"],stability:s},capability:{key:"agent.execution",version:"1.0.0"},io:{input:u,output:g},policy:{auth:"admin",pii:[]}});const c=new e({name:"AgentTaskTreeInput",fields:{agentRunId:{type:t.ID(),isOptional:!1}}}),k=new e({name:"AgentTaskTreeOutput",fields:{agentRunId:{type:t.ID(),isOptional:!1},tasks:{type:t.JSONObject(),isOptional:!1}}});export const AgentTaskTreeQuery=l({meta:{key:"agent.task.tree",title:"Get Agent Task Tree",version:"1.0.0",description:"Retrieve the full task tree for a given agent run.",goal:"Allow clients to inspect task topology and status for an agent run.",context:"Returns a flat list of task nodes; clients build the tree from parent refs.",domain:n,owners:a,tags:[...i,"task","tree","query"],stability:s},capability:{key:"agent.execution",version:"1.0.0"},io:{input:c,output:k},policy:{auth:"user",pii:[]}});const d=new e({name:"AgentTaskAssignInput",fields:{taskId:{type:t.ID(),isOptional:!1},assigneeId:{type:t.ID(),isOptional:!1},assigneeType:{type:t.String_unsecure(),isOptional:!1}}}),y=new e({name:"AgentTaskAssignOutput",fields:{taskId:{type:t.ID(),isOptional:!1},assigned:{type:t.Boolean(),isOptional:!1},assignedAt:{type:t.DateTime(),isOptional:!0}}});export const AgentTaskAssignCommand=o({meta:{key:"agent.task.assign",title:"Assign Agent Task",version:"1.0.0",description:"Assign an agent task to a person or agent entity.",goal:"Route task work to a specific person or sub-agent.",context:"Assignment is advisory; the runner still owns execution ordering.",domain:n,owners:a,tags:[...i,"task","assign"],stability:s},capability:{key:"agent.execution",version:"1.0.0"},io:{input:d,output:y},policy:{auth:"user",pii:[]}});

package/dist/node/agent/commands/graphCompose.command.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{docId as o}from"../../docs/registry.js";import{defineCommand as a}from"../../operations/index.js";import{AGENT_DOMAIN as n,AGENT_OWNERS as r,AGENT_STABILITY as s,AGENT_TAGS as p}from"../constants.js";export const GRAPH_COMPOSE_BUDGET={maxInputTokens:2500,maxOutputTokens:1200,hardCapUsd:0.03};const i=[...p,"graph","ai","compose","generation","m5"],d=new t({name:"GraphComposeInput",fields:{spec:{type:e.NonEmptyString(),isOptional:!1},contextGraphId:{type:e.ID(),isOptional:!0},style:{type:e.String_unsecure(),isOptional:!0},maxNodes:{type:e.Int_unsecure(),isOptional:!0},dryRun:{type:e.Boolean(),isOptional:!0}}}),c=new t({name:"GraphComposeOutput",fields:{construction:{type:e.JSONObject(),isOptional:!1},nodeCount:{type:e.Int_unsecure(),isOptional:!1},edgeCount:{type:e.Int_unsecure(),isOptional:!1},applied:{type:e.Boolean(),isOptional:!1},budgetUsed:{type:e.JSONObject(),isOptional:!1}}});export const GraphComposeDocBlock={id:"docs.tech.graph.compose",title:"graph.compose — build a graph from a NL spec",summary:"Generates a GraphConstruction[] mutation sequence from a natural-language description. Supports dry-run preview. Budget: 2 500 in / 1 200 out / $0.030.",kind:"reference",visibility:"public",route:"/docs/tech/graph/compose",tags:["automation","agent","execution","graph","ai","compose","generation","m5"],body:'# graph.compose\n\nTranslates a natural-language description into a `GraphConstruction[]` mutation\nsequence that the graph runtime can apply to create or extend a graph.\n\n## Construction types\n\n### `create_node`\n```json\n{ "type": "create_node", "nodeId": "n1", "label": "Build", "kind": "task", "metadata": {} }\n```\n\n### `create_edge`\n```json\n{ "type": "create_edge", "edgeId": "e1", "from": "n1", "to": "n2", "label": "triggers", "kind": "flow" }\n```\n\n### `set_metadata`\n```json\n{ "type": "set_metadata", "nodeId": "n1", "metadata": { "owner": "ci-team" } }\n```\n\n## Style hints\n\n- `workflow`   — linear/branching task sequence\n- `sequence`   — time-ordered event chain\n- `hierarchy`  — parent/child containment tree\n- `dependency` — directed dependency graph\n- `freeform`   — no structural bias (default)\n\n## Dry run\n\nPass `dryRun: true` to preview the construction without applying it.\n`applied` is `false` in the response; no state is mutated.\n\n## Budget (M5 P2/W2.3)\nmaxInputTokens=2 500 · maxOutputTokens=1 200 · hardCapUsd=$0.030'},GraphComposeCommand=a({meta:{key:"graph.compose",title:"Graph compose",version:"1.0.0",description:"Build a graph from a natural-language spec, producing a GraphConstruction[] mutation sequence.",goal:"Let AI agents scaffold entire graphs from plain-English descriptions, with dry-run preview.",context:["Outputs an ordered GraphConstruction[] array: create_node | create_edge | set_metadata.","contextGraphId is optional — omit to compose a fresh graph, supply to append into existing.","style hint guides structural layout: workflow | sequence | hierarchy | dependency | freeform.","maxNodes soft cap (default 30, max 100) prevents runaway generation.","dryRun: true returns the construction without applying it.","Budget: maxInputTokens=2500, maxOutputTokens=1200, hardCapUsd=$0.030.","Emits ai.graph.compose observability event on every invocation."].join(" "),domain:n,owners:r,tags:i,stability:s,docId:[o("docs.tech.graph.compose")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:d,output:c,errors:{BUDGET_EXCEEDED:{description:"Token or cost budget exceeded for this invocation.",http:429,when:"Input exceeds maxInputTokens or cost would exceed hardCapUsd."},INVALID_SPEC:{description:"The natural-language spec could not be interpreted as a graph.",http:422,when:"spec is empty, self-contradictory, or too vague to generate any nodes."},SPEC_TOO_COMPLEX:{description:"The spec would generate more nodes than maxNodes allows.",http:422,when:"Estimated node count exceeds the maxNodes cap (100 absolute max)."},CONTEXT_GRAPH_NOT_FOUND:{description:"The supplied contextGraphId does not exist.",http:404,when:"contextGraphId is provided but references a graph that cannot be found."},INVALID_STYLE:{description:"The style hint is not one of the supported values.",http:422,when:"style is provided but is not workflow | sequence | hierarchy | dependency | freeform."}}},policy:{auth:"user"}});

package/dist/node/agent/commands/graphEdit.command.js

@@ -0,0 +1,25 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{docId as o}from"../../docs/registry.js";import{defineCommand as a}from"../../operations/index.js";import{AGENT_DOMAIN as i,AGENT_OWNERS as n,AGENT_STABILITY as d,AGENT_TAGS as r}from"../constants.js";export const GRAPH_EDIT_BUDGET={maxInputTokens:1500,maxOutputTokens:500,hardCapUsd:0.025};const s=[...r,"graph","ai","edit","mutation","m5"],p=new t({name:"GraphEditInput",fields:{contextGraphId:{type:e.ID(),isOptional:!1},ops:{type:e.JSONObject(),isOptional:!1},confirmationToken:{type:e.String_unsecure(),isOptional:!0}}}),m=new t({name:"GraphEditOutput",fields:{appliedOps:{type:e.JSONObject(),isOptional:!1},rejectedOps:{type:e.JSONObject(),isOptional:!1},budgetUsed:{type:e.JSONObject(),isOptional:!1}}});export const GraphEditDocBlock={id:"docs.tech.graph.edit",title:"graph.edit — LLM-driven node/edge mutations",summary:"Single command for all structural graph mutations (add/remove/rename node, add/remove edge, edit metadata). Per-call budget: 1 500 in / 500 out / $0.025. Requires confirmation token for destructive ops.",kind:"reference",visibility:"public",route:"/docs/tech/graph/edit",tags:["automation","agent","execution","graph","ai","edit","mutation","m5"],body:`# graph.edit
+
+Executes a batch of structural graph mutations in a single LLM tool call.
+
+## Supported ops (discriminated by \`type\`)
+
+| type | Description |
+|---|---|
+| \`add_node\` | Insert node (id, label?, kind?, metadata?) |
+| \`remove_node\` | Delete node + all incident edges |
+| \`rename_node\` | Update node label |
+| \`edit_metadata\` | Patch metadata on node or edge |
+| \`add_edge\` | Insert directed edge (id, from, to, label?, kind?) |
+| \`remove_edge\` | Delete edge |
+
+Max **20 ops per call** to stay within the token budget.
+
+## Confirmation requirement
+
+Destructive ops (\`remove_node\`, \`remove_edge\`) require a \`confirmationToken\`
+issued by the AI suggestion confirmation UX (W7.4). The command returns
+\`CONFIRMATION_REQUIRED\` (403) when the token is absent or invalid.
+
+## Budget (M5 P2/W2.1)
+maxInputTokens=1 500 · maxOutputTokens=500 · hardCapUsd=$0.025`},GraphEditCommand=a({meta:{key:"graph.edit",title:"Graph edit",version:"1.0.0",description:"Single LLM tool for node/edge mutations: add, remove, rename, edit metadata.",goal:"Let AI agents apply confirmed structural graph mutations in a single, budget-bounded call.",context:["Covers all mutation types via a discriminated ops array (add_node, remove_node,","rename_node, edit_metadata, add_edge, remove_edge). Max 20 ops/call.","Destructive ops require a confirmationToken from the suggestion UX (W7.4).","Budget: maxInputTokens=1500, maxOutputTokens=500, hardCapUsd=$0.025.","Emits ai.graph.edit observability event on every invocation."].join(" "),domain:i,owners:n,tags:s,stability:d,docId:[o("docs.tech.graph.edit")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:p,output:m,errors:{BUDGET_EXCEEDED:{description:"Token or cost budget exceeded for this invocation.",http:429,when:"Input exceeds maxInputTokens or cost would exceed hardCapUsd."},INVALID_OPS:{description:"One or more ops in the array have an invalid shape.",http:422,when:"An op is missing required fields or has an unknown type."},CONFIRMATION_REQUIRED:{description:"Destructive ops require a valid confirmationToken.",http:403,when:"remove_node or remove_edge ops present but confirmationToken is absent or invalid."},ENTITY_NOT_FOUND:{description:"A referenced nodeId or edgeId does not exist in the graph.",http:404,when:"An op targets a node or edge that is not present in contextGraphId."},TOO_MANY_OPS:{description:"Ops array exceeds the 20-op-per-call limit.",http:422,when:"ops.length > 20."}}},policy:{auth:"user"}});

package/dist/node/agent/commands/graphOps.command.js

@@ -0,0 +1,31 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{docId as a}from"../../docs/registry.js";import{defineCommand as r}from"../../operations/index.js";import{AGENT_DOMAIN as s,AGENT_OWNERS as n,AGENT_STABILITY as o,AGENT_TAGS as u}from"../constants.js";export const GRAPH_AI_BUDGETS={"graph.search":{maxInputTokens:1000,maxOutputTokens:200,hardCapUsd:0.005},"graph.filter":{maxInputTokens:1200,maxOutputTokens:300,hardCapUsd:0.008},"graph.cluster":{maxInputTokens:1500,maxOutputTokens:400,hardCapUsd:0.011},"graph.suggest":{maxInputTokens:2000,maxOutputTokens:800,hardCapUsd:0.02}};const i=[...u,"graph","ai","nlq","m3"],p=new t({name:"GraphSearchInput",fields:{query:{type:e.NonEmptyString(),isOptional:!1},contextGraphId:{type:e.ID(),isOptional:!1}}}),c=new t({name:"GraphSearchOutput",fields:{nodeIds:{type:e.JSONObject(),isOptional:!1},edgeIds:{type:e.JSONObject(),isOptional:!1},viewportSuggestion:{type:e.JSONObject(),isOptional:!0}}});export const GraphSearchDocBlock={id:"docs.tech.graph.search",title:"graph.search — NL node search",summary:"Natural-language graph search returning ranked node/edge IDs and an optional viewport suggestion. Budget: 1 000 in / 200 out / $0.005.",kind:"reference",visibility:"public",route:"/docs/tech/graph/search",tags:["automation","agent","execution","graph","ai","nlq","m3"],body:"# graph.search\n\nTranslates a natural-language query into ranked `nodeIds` and `edgeIds`.\nAlso returns an optional viewport suggestion `{ centerX, centerY, zoom }`\nthe canvas can animate to.\n\n## Budget (`m3-p0-ai-cost-ceiling.md`)\nmaxInputTokens=1 000 · maxOutputTokens=200 · hardCapUsd=$0.005"},GraphSearchCommand=r({meta:{key:"graph.search",title:"Graph search",version:"1.0.0",description:"Natural-language graph search returning ranked node/edge IDs.",goal:"Let users find graph nodes and edges via plain-English queries.",context:["AI-powered search over the current graph context.","Budget: maxInputTokens=1000, maxOutputTokens=200, hardCapUsd=$0.005.","Emits ai.graph.query observability event on every invocation.","Cost enforcement at @lssm/lib.ai-agent layer."].join(" "),domain:s,owners:n,tags:i,stability:o,docId:[a("docs.tech.graph.search")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:p,output:c,errors:{BUDGET_EXCEEDED:{description:"Token or cost budget exceeded for this invocation.",http:429,when:"Input exceeds maxInputTokens or cost would exceed hardCapUsd."},INVALID_QUERY:{description:"The NL query could not be interpreted.",http:422,when:"Query is empty, too ambiguous, or refers to non-existent context."}}},policy:{auth:"user"}});const l=new t({name:"GraphFilterInput",fields:{query:{type:e.NonEmptyString(),isOptional:!1},contextGraphId:{type:e.ID(),isOptional:!1}}}),d=new t({name:"GraphFilterOutput",fields:{filter:{type:e.JSONObject(),isOptional:!1},description:{type:e.String_unsecure(),isOptional:!1}}});export const GraphFilterDocBlock={id:"docs.tech.graph.filter",title:"graph.filter — NL filter generation",summary:"Translates a NL query into a GraphFilterSpec for the filter rack. Budget: 1 200 in / 300 out / $0.008.",kind:"reference",visibility:"public",route:"/docs/tech/graph/filter",tags:["automation","agent","execution","graph","ai","nlq","m3"],body:`# graph.filter
+
+Translates a natural-language filter request into a \`GraphFilterSpec\`
+JSON that the filter rack can apply directly.
+
+## Budget (\`m3-p0-ai-cost-ceiling.md\`)
+maxInputTokens=1 200 · maxOutputTokens=300 · hardCapUsd=$0.008`},GraphFilterCommand=r({meta:{key:"graph.filter",title:"Graph filter",version:"1.0.0",description:"NL query to GraphFilterSpec for the filter rack.",goal:"Let users create graph filters via plain-English queries.",context:["Outputs a serialised GraphFilterSpec usable by the filter rack and FacetPanel.","Budget: maxInputTokens=1200, maxOutputTokens=300, hardCapUsd=$0.008.","Emits ai.graph.query observability event."].join(" "),domain:s,owners:n,tags:i,stability:o,docId:[a("docs.tech.graph.filter")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:l,output:d,errors:{BUDGET_EXCEEDED:{description:"Token or cost budget exceeded.",http:429,when:"Input exceeds maxInputTokens or cost would exceed hardCapUsd."},INVALID_QUERY:{description:"The NL query could not be converted to a valid filter.",http:422,when:"Query is too ambiguous or refers to unknown field names."}}},policy:{auth:"user"}});const g=new t({name:"GraphClusterInput",fields:{query:{type:e.NonEmptyString(),isOptional:!1},contextGraphId:{type:e.ID(),isOptional:!1},maxClusters:{type:e.Int_unsecure(),isOptional:!0}}}),h=new t({name:"GraphClusterOutput",fields:{clusters:{type:e.JSONObject(),isOptional:!1},rationale:{type:e.String_unsecure(),isOptional:!1}}});export const GraphClusterDocBlock={id:"docs.tech.graph.cluster",title:"graph.cluster — NL cluster grouping",summary:"Generates cluster groupings with labels from a NL strategy query. Budget: 1 500 in / 400 out / $0.011.",kind:"reference",visibility:"public",route:"/docs/tech/graph/cluster",tags:["automation","agent","execution","graph","ai","nlq","m3"],body:`# graph.cluster
+
+Groups graph nodes into labelled clusters based on a natural-language
+clustering strategy (e.g., "group by team ownership", "cluster by data flow").
+
+## Output shape
+\`clusters: Array<{ id, label, nodeIds, color? }>\`
+
+## Budget (\`m3-p0-ai-cost-ceiling.md\`)
+maxInputTokens=1 500 · maxOutputTokens=400 · hardCapUsd=$0.011`},GraphClusterCommand=r({meta:{key:"graph.cluster",title:"Graph cluster",version:"1.0.0",description:"NL strategy query to cluster groupings with labels.",goal:"Let users group graph nodes into meaningful clusters via plain-English.",context:["Complements the useGraphCluster hook (W4.6). Outputs cluster descriptors","that the hook can apply directly.","Budget: maxInputTokens=1500, maxOutputTokens=400, hardCapUsd=$0.011.","Emits ai.graph.query observability event."].join(" "),domain:s,owners:n,tags:i,stability:o,docId:[a("docs.tech.graph.cluster")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:g,output:h,errors:{BUDGET_EXCEEDED:{description:"Token or cost budget exceeded.",http:429,when:"Input exceeds maxInputTokens or cost would exceed hardCapUsd."},INVALID_QUERY:{description:"The clustering strategy could not be interpreted.",http:422,when:"Query is too vague or context graph has no clusterable structure."}}},policy:{auth:"user"}});const m=new t({name:"GraphSuggestInput",fields:{query:{type:e.NonEmptyString(),isOptional:!1},contextGraphId:{type:e.ID(),isOptional:!1},maxSuggestions:{type:e.Int_unsecure(),isOptional:!0}}}),y=new t({name:"GraphSuggestOutput",fields:{suggestions:{type:e.JSONObject(),isOptional:!1},truncated:{type:e.Boolean(),isOptional:!1}}});export const GraphSuggestDocBlock={id:"docs.tech.graph.suggest",title:"graph.suggest — AI graph-edit suggestions",summary:"Ranked read-only graph-edit suggestions. Mutations require explicit user confirmation. Budget: 2 000 in / 800 out / $0.020.",kind:"reference",visibility:"public",route:"/docs/tech/graph/suggest",tags:["automation","agent","execution","graph","ai","nlq","m3"],body:`# graph.suggest
+
+Returns ranked suggestions for graph edits based on a natural-language request.
+
+**Read-only**: suggestions are never auto-applied. Each must be confirmed via
+the AI suggestion confirmation UX (W7.4) before any mutation occurs.
+
+## Output shape
+\`suggestions: Array<{ id, label, description, confidence, action }>\`
+
+## Truncation
+Output >800 tokens is halted mid-stream; \`truncated: true\` is returned.
+Users may request expansion.
+
+## Budget (\`m3-p0-ai-cost-ceiling.md\`)
+maxInputTokens=2 000 · maxOutputTokens=800 · hardCapUsd=$0.020`},GraphSuggestCommand=r({meta:{key:"graph.suggest",title:"Graph suggest",version:"1.0.0",description:"Ranked read-only AI suggestions for graph edits.",goal:"Surface AI-driven graph improvement ideas without auto-applying mutations.",context:["Suggestions require explicit human confirmation (W7.4) before any mutation.","Output truncated at 800 tokens — truncated=true indicates partial result.","Budget: maxInputTokens=2000, maxOutputTokens=800, hardCapUsd=$0.020.","Emits ai.graph.query observability event."].join(" "),domain:s,owners:n,tags:i,stability:o,docId:[a("docs.tech.graph.suggest")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:m,output:y,errors:{BUDGET_EXCEEDED:{description:"Token or cost budget exceeded.",http:429,when:"Input exceeds maxInputTokens or cost would exceed hardCapUsd."},INVALID_QUERY:{description:"The suggestion request could not be interpreted.",http:422,when:"Query is empty, contradictory, or the context graph is empty."}}},policy:{auth:"user"}});

package/dist/node/agent/commands/graphRefactor.command.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{docId as r}from"../../docs/registry.js";import{defineCommand as a}from"../../operations/index.js";import{AGENT_DOMAIN as o,AGENT_OWNERS as n,AGENT_STABILITY as s,AGENT_TAGS as p}from"../constants.js";export const GRAPH_REFACTOR_BUDGET={maxInputTokens:2000,maxOutputTokens:600,hardCapUsd:0.035};const i=[...p,"graph","ai","refactor","pattern","m5"],d=new t({name:"GraphRefactorInput",fields:{contextGraphId:{type:e.ID(),isOptional:!1},operation:{type:e.JSONObject(),isOptional:!1},dryRun:{type:e.Boolean(),isOptional:!0}}}),u=new t({name:"GraphRefactorOutput",fields:{preview:{type:e.JSONObject(),isOptional:!1},applied:{type:e.Boolean(),isOptional:!1},resultGraphId:{type:e.ID(),isOptional:!0},budgetUsed:{type:e.JSONObject(),isOptional:!1}}});export const GraphRefactorDocBlock={id:"docs.tech.graph.refactor",title:"graph.refactor — pattern-level graph transformations",summary:"Four structural refactoring ops: rename-by-pattern, extract-subgraph, merge-nodes, split-node. Supports dryRun preview. Budget: 2 000 in / 600 out / $0.035.",kind:"reference",visibility:"public",route:"/docs/tech/graph/refactor",tags:["automation","agent","execution","graph","ai","refactor","pattern","m5"],body:'# graph.refactor\n\nApplies a single pattern-level structural transformation to a graph. Choose the\noperation type via `operation.type`.\n\n## Supported operations\n\n### `rename_by_pattern`\nRenames node/edge labels matching a JS regex pattern.\n`scope`: `"nodes"` | `"edges"` | `"both"`.\n\n### `extract_subgraph`\nMoves specified nodes (and edges between them) into a new sub-graph.\nCross-boundary edges are preserved as stubs. Returns `resultGraphId`.\n\n### `merge_nodes`\nCollapses `sourceNodeIds` into `targetNodeId`.\n`strategy`: `"union"` (all edges kept) | `"intersect"` (shared edges only).\n\n### `split_node`\nExpands one node into multiple partitions. Edges re-distributed by kind affinity.\n\n## Dry run\n\nPass `dryRun: true` to preview the diff without mutating state.\nThe `preview` field in the output is always populated; `applied` is `false`.\n\n## Budget (M5 P2/W2.2)\nmaxInputTokens=2 000 · maxOutputTokens=600 · hardCapUsd=$0.035'},GraphRefactorCommand=a({meta:{key:"graph.refactor",title:"Graph refactor",version:"1.0.0",description:"Pattern-level graph transformations: rename-by-pattern, extract-subgraph, merge-nodes, split-node.",goal:"Let AI agents restructure graphs at the pattern level, with dry-run preview support.",context:["Discriminated by operation.type: rename_by_pattern | extract_subgraph | merge_nodes | split_node.","dryRun: true returns a structural diff preview without mutating state.","extract_subgraph emits resultGraphId for the new sub-graph.","Budget: maxInputTokens=2000, maxOutputTokens=600, hardCapUsd=$0.035.","Emits ai.graph.refactor observability event on every invocation."].join(" "),domain:o,owners:n,tags:i,stability:s,docId:[r("docs.tech.graph.refactor")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:d,output:u,errors:{BUDGET_EXCEEDED:{description:"Token or cost budget exceeded for this invocation.",http:429,when:"Input exceeds maxInputTokens or cost would exceed hardCapUsd."},INVALID_OPERATION:{description:"The operation object has an unknown type or missing required fields.",http:422,when:"operation.type is not one of the four supported values, or required fields are absent."},ENTITY_NOT_FOUND:{description:"A referenced nodeId or edgeId does not exist in the graph.",http:404,when:"operation references nodes/edges not present in contextGraphId."},INVALID_PATTERN:{description:"The regex pattern in rename_by_pattern is syntactically invalid.",http:422,when:"operation.pattern cannot be compiled as a JavaScript RegExp."},MERGE_TARGET_NOT_IN_SOURCES:{description:"targetNodeId must be one of the sourceNodeIds.",http:422,when:"merge_nodes operation has targetNodeId not in sourceNodeIds."}}},policy:{auth:"user"}});

package/dist/node/agent/commands/graphSuggestEvolution.command.js

@@ -0,0 +1,35 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{docId as o}from"../../docs/registry.js";import{defineCommand as n}from"../../operations/index.js";import{AGENT_DOMAIN as s,AGENT_OWNERS as i,AGENT_STABILITY as a,AGENT_TAGS as r}from"../constants.js";export const GRAPH_SUGGEST_EVOLUTION_BUDGET={maxInputTokens:2500,maxOutputTokens:1000,hardCapUsd:0.028};const u=[...r,"graph","ai","evolution","suggestions","m5"],g=new t({name:"GraphSuggestEvolutionInput",fields:{contextGraphId:{type:e.ID(),isOptional:!1},focusArea:{type:e.String_unsecure(),isOptional:!0},maxSuggestions:{type:e.Int_unsecure(),isOptional:!0}}}),c=new t({name:"GraphSuggestEvolutionOutput",fields:{suggestions:{type:e.JSONObject(),isOptional:!1},truncated:{type:e.Boolean(),isOptional:!1},budgetUsed:{type:e.JSONObject(),isOptional:!1}}});export const GraphSuggestEvolutionDocBlock={id:"docs.tech.graph.suggest-evolution",title:"graph.suggest_evolution — proactive graph evolution suggestions",summary:"Ranks structural and semantic improvement suggestions for a graph: missing reviewer, missing retry, weak path, isolated node, naming inconsistency, missing feedback loop, circular dependency, high fan-out. Budget: 2 500 in / 1 000 out / $0.028.",kind:"reference",visibility:"public",route:"/docs/tech/graph/suggest-evolution",tags:["automation","agent","execution","graph","ai","evolution","suggestions","m5"],body:`# graph.suggest_evolution
+
+Analyses the current graph and returns ranked proactive improvement suggestions.
+Suggestions are **read-only** — nothing is applied automatically.
+
+## Suggestion kinds
+
+| kind | Description |
+|---|---|
+| \`missing_reviewer\` | A node or flow has no assigned reviewer / approval step |
+| \`missing_retry\`    | An error path has no retry or back-off edge |
+| \`weak_path\`        | A critical path has only one route (no redundancy) |
+| \`isolated_node\`    | A node has neither incoming nor outgoing edges |
+| \`naming_inconsistency\` | Labels diverge from the dominant naming style |
+| \`missing_feedback_loop\` | A workflow has no feedback or notification branch |
+| \`circular_dependency\` | A cycle exists that may indicate a design issue |
+| \`high_fan_out\`     | A node has an unusually large number of outgoing edges |
+
+## focusArea
+
+Narrow the scan to reduce cost and noise:
+- \`"reliability"\` — retry, redundancy, failure-path coverage
+- \`"coverage"\`    — reviewer presence, approval steps, feedback loops
+- \`"connectivity"\` — isolated nodes, weak paths, high fan-out
+- \`"naming"\`      — label consistency
+- \`"all"\`         — full scan (default)
+
+## Acting on suggestions
+
+Each suggestion includes a \`suggestedFix\` string.
+Pass that text back to \`graph.edit\` or \`graph.compose\` to apply the fix
+after confirming through the AI suggestion UX (W7.4).
+
+## Budget (M5 P2/W2.4)
+maxInputTokens=2 500 · maxOutputTokens=1 000 · hardCapUsd=$0.028`},GraphSuggestEvolutionCommand=n({meta:{key:"graph.suggest_evolution",title:"Graph suggest evolution",version:"1.0.0",description:"Proactive ranked suggestions for improving graph structure and coverage.",goal:"Surface structural and semantic weaknesses (missing retry, weak path, etc.) before they become incidents.",context:["Returns EvolutionSuggestion[] ranked by confidence × severity.","Kinds: missing_reviewer | missing_retry | weak_path | isolated_node |","naming_inconsistency | missing_feedback_loop | circular_dependency | high_fan_out.","focusArea narrows the scan: reliability | coverage | connectivity | naming | all.","maxSuggestions defaults to 5, max 20. truncated=true when output budget hit.","Read-only — no mutations applied. suggestedFix text guides follow-up graph.edit calls.","Budget: maxInputTokens=2500, maxOutputTokens=1000, hardCapUsd=$0.028.","Emits ai.graph.suggest_evolution observability event on every invocation."].join(" "),domain:s,owners:i,tags:u,stability:a,docId:[o("docs.tech.graph.suggest-evolution")]},capability:{key:"agent.execution",version:"1.0.0"},io:{input:g,output:c,errors:{BUDGET_EXCEEDED:{description:"Token or cost budget exceeded for this invocation.",http:429,when:"Input exceeds maxInputTokens or cost would exceed hardCapUsd."},EMPTY_GRAPH:{description:"The graph has no nodes or edges to analyse.",http:422,when:"contextGraphId references a graph with zero nodes."},CONTEXT_GRAPH_NOT_FOUND:{description:"The supplied contextGraphId does not exist.",http:404,when:"contextGraphId references a graph that cannot be found."},INVALID_FOCUS_AREA:{description:"The focusArea value is not one of the supported categories.",http:422,when:"focusArea is provided but is not reliability | coverage | connectivity | naming | all."}}},policy:{auth:"user"}});

package/dist/node/agent/commands/index.js

@@ -0,0 +1 @@
+export*from"./agentApprovals.command.js";export*from"./agentCancel.command.js";export*from"./agentRun.command.js";export*from"./agentTaskOps.command.js";export*from"./graphCompose.command.js";export*from"./graphEdit.command.js";export*from"./graphOps.command.js";export*from"./graphRefactor.command.js";export*from"./graphSuggestEvolution.command.js";

package/dist/node/agent/constants.js

@@ -0,0 +1 @@
+import{StabilityEnum as t,TagsEnum as o}from"../ownership.js";export const AGENT_DOMAIN="agent",AGENT_OWNERS=["platform.ai"],AGENT_TAGS=[o.Automation,"agent","execution"],AGENT_STABILITY=t.Beta;

package/dist/node/agent/contracts.js

@@ -0,0 +1 @@
+import{AgentExecutionCapability as e}from"./capabilities/index.js";import{AgentApprovalsCommand as r,AgentCancelCommand as n,AgentRunCommand as i}from"./commands/index.js";import{AgentApprovalRequestedEvent as o,AgentRunCompletedEvent as s,AgentRunFailedEvent as a,AgentRunStartedEvent as g}from"./events/index.js";import{AgentRunForm as p}from"./forms/index.js";import{AgentRunAuditPresentation as m}from"./presentations/index.js";import{AgentArtifactsQuery as u,AgentStatusQuery as y}from"./queries/index.js";import{AgentRunsDataView as c}from"./views/index.js";export const agentOperationContracts={AgentRunCommand:i,AgentCancelCommand:n,AgentApprovalsCommand:r,AgentStatusQuery:y,AgentArtifactsQuery:u},agentEventContracts={AgentRunStartedEvent:g,AgentRunCompletedEvent:s,AgentRunFailedEvent:a,AgentApprovalRequestedEvent:o},agentCapabilityContracts={AgentExecutionCapability:e},agentDataViewContracts={AgentRunsDataView:c},agentFormContracts={AgentRunForm:p},agentPresentationContracts={AgentRunAuditPresentation:m};export function registerAgentOperations(t){return t.register(i).register(n).register(r).register(y).register(u)}export function registerAgentEvents(t){return t.register(g).register(s).register(a).register(o)}export function registerAgentCapabilities(t){return t.register(e)}export function registerAgentDataViews(t){return t.register(c)}export function registerAgentForms(t){return t.register(p)}export function registerAgentPresentations(t){return t.register(m)}

package/dist/node/agent/events/agentApprovalRequested.event.js

@@ -0,0 +1,4 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{docId as a}from"../../docs/registry.js";import{defineEvent as o}from"../../events.js";import{AGENT_DOMAIN as r,AGENT_OWNERS as p,AGENT_STABILITY as i,AGENT_TAGS as n}from"../constants.js";export const AgentApprovalRequestedPayload=new t({name:"AgentApprovalRequestedPayload",fields:{runId:{type:e.ID(),isOptional:!1},approvalId:{type:e.ID(),isOptional:!1},reason:{type:e.String_unsecure(),isOptional:!0},requestedAt:{type:e.DateTime(),isOptional:!1}}}),AgentApprovalRequestedDocBlock={id:"docs.tech.agent.approval.requested",title:"Agent approval requested event",summary:"Emitted when approval is required.",kind:"reference",visibility:"public",route:"/docs/tech/agent/approval/requested",tags:["agent","event","approval"],body:`# agent.approval.requested
+
+Emitted when an approval gate is triggered.
+`},AgentApprovalRequestedEvent=o({meta:{key:"agent.approval.requested",version:"1.0.0",description:"Emitted when an approval is required for an agent action.",domain:r,owners:p,tags:[...n,"approval"],stability:i,docId:[a("docs.tech.agent.approval.requested")]},capability:{key:"agent.execution",version:"1.0.0"},pii:["reason"],payload:AgentApprovalRequestedPayload});

package/dist/node/agent/events/agentRunCompleted.event.js

@@ -0,0 +1,4 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{docId as n}from"../../docs/registry.js";import{defineEvent as o}from"../../events.js";import{AGENT_DOMAIN as i,AGENT_OWNERS as a,AGENT_STABILITY as s,AGENT_TAGS as c}from"../constants.js";export const AgentRunCompletedPayload=new t({name:"AgentRunCompletedPayload",fields:{runId:{type:e.ID(),isOptional:!1},agentKey:{type:e.String_unsecure(),isOptional:!1},status:{type:e.String_unsecure(),isOptional:!1},completedAt:{type:e.DateTime(),isOptional:!1},contextSnapshotId:{type:e.ID(),isOptional:!0}}}),AgentRunCompletedDocBlock={id:"docs.tech.agent.run.completed",title:"Agent run completed event",summary:"Emitted when an agent run completes.",kind:"reference",visibility:"public",route:"/docs/tech/agent/run/completed",tags:["agent","event"],body:`# agent.run.completed
+
+Emitted when a run completes successfully.
+`},AgentRunCompletedEvent=o({meta:{key:"agent.run.completed",version:"1.0.0",description:"Emitted when an agent run completes successfully.",domain:i,owners:a,tags:[...c,"run"],stability:s,docId:[n("docs.tech.agent.run.completed")]},capability:{key:"agent.execution",version:"1.0.0"},pii:[],payload:AgentRunCompletedPayload});

package/dist/node/agent/events/agentRunFailed.event.js

@@ -0,0 +1,4 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{docId as n}from"../../docs/registry.js";import{defineEvent as i}from"../../events.js";import{AGENT_DOMAIN as a,AGENT_OWNERS as o,AGENT_STABILITY as r,AGENT_TAGS as s}from"../constants.js";export const AgentRunFailedPayload=new t({name:"AgentRunFailedPayload",fields:{runId:{type:e.ID(),isOptional:!1},agentKey:{type:e.String_unsecure(),isOptional:!1},status:{type:e.String_unsecure(),isOptional:!1},failedAt:{type:e.DateTime(),isOptional:!1},errorMessage:{type:e.String_unsecure(),isOptional:!0},problem:{type:e.JSONObject(),isOptional:!0},contextSnapshotId:{type:e.ID(),isOptional:!0}}}),AgentRunFailedDocBlock={id:"docs.tech.agent.run.failed",title:"Agent run failed event",summary:"Emitted when an agent run fails.",kind:"reference",visibility:"public",route:"/docs/tech/agent/run/failed",tags:["agent","event"],body:`# agent.run.failed
+
+Emitted when a run terminates with failure.
+`},AgentRunFailedEvent=i({meta:{key:"agent.run.failed",version:"1.0.0",description:"Emitted when an agent run fails.",domain:a,owners:o,tags:[...s,"run"],stability:r,docId:[n("docs.tech.agent.run.failed")]},capability:{key:"agent.execution",version:"1.0.0"},pii:["errorMessage"],payload:AgentRunFailedPayload});

package/dist/node/agent/events/agentRunStarted.event.js

@@ -0,0 +1,4 @@
+import{ScalarTypeEnum as t,SchemaModel as e}from"@lssm/lib.schema";import{docId as n}from"../../docs/registry.js";import{defineEvent as a}from"../../events.js";import{AGENT_DOMAIN as r,AGENT_OWNERS as i,AGENT_STABILITY as o,AGENT_TAGS as s}from"../constants.js";export const AgentRunStartedPayload=new e({name:"AgentRunStartedPayload",fields:{runId:{type:t.ID(),isOptional:!1},agentKey:{type:t.String_unsecure(),isOptional:!1},status:{type:t.String_unsecure(),isOptional:!1},startedAt:{type:t.DateTime(),isOptional:!1},contextSnapshotId:{type:t.ID(),isOptional:!0}}}),AgentRunStartedDocBlock={id:"docs.tech.agent.run.started",title:"Agent run started event",summary:"Emitted when an agent run starts.",kind:"reference",visibility:"public",route:"/docs/tech/agent/run/started",tags:["agent","event"],body:`# agent.run.started
+
+Emitted when an agent run begins execution.
+`},AgentRunStartedEvent=a({meta:{key:"agent.run.started",version:"1.0.0",description:"Emitted when an agent run starts executing.",domain:r,owners:i,tags:[...s,"run"],stability:o,docId:[n("docs.tech.agent.run.started")]},capability:{key:"agent.execution",version:"1.0.0"},pii:[],payload:AgentRunStartedPayload});

package/dist/node/agent/events/index.js

@@ -0,0 +1 @@
+export*from"./agentApprovalRequested.event.js";export*from"./agentRunCompleted.event.js";export*from"./agentRunFailed.event.js";export*from"./agentRunStarted.event.js";

package/dist/node/agent/forms/agentRun.form.js

@@ -0,0 +1,4 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{docId as n}from"../../docs/registry.js";import{defineFormSpec as o}from"../../forms/forms.js";import{AGENT_DOMAIN as r,AGENT_OWNERS as a,AGENT_STABILITY as i,AGENT_TAGS as l}from"../constants.js";const m=new t({name:"AgentRunFormModel",fields:{agentKey:{type:e.NonEmptyString(),isOptional:!1},prompt:{type:e.String_unsecure(),isOptional:!0},contextSnapshotId:{type:e.ID(),isOptional:!0},mode:{type:e.String_unsecure(),isOptional:!0},priority:{type:e.Int_unsecure(),isOptional:!0}}});export const AgentRunFormDocBlock={id:"docs.tech.agent.run.form",title:"Agent run form",summary:"Form specification for launching an agent run.",kind:"reference",visibility:"public",route:"/docs/tech/agent/run/form",tags:["agent","form"],body:`# agent.run.form
+
+Form surface used by Studio to submit agent runs.
+`},AgentRunForm=o({meta:{key:"agent.run.form",title:"Run Agent",version:"1.0.0",description:"Form to launch a background agent run.",domain:r,owners:a,tags:[...l,"run"],stability:i,docId:[n("docs.tech.agent.run.form")]},model:m,fields:[{kind:"text",name:"agentKey",labelI18n:"Agent",placeholderI18n:"agent.key",required:!0},{kind:"textarea",name:"prompt",labelI18n:"Prompt",placeholderI18n:"Describe the task"},{kind:"text",name:"contextSnapshotId",labelI18n:"Context Snapshot",placeholderI18n:"snapshot id"},{kind:"text",name:"mode",labelI18n:"Mode",placeholderI18n:"background"},{kind:"text",name:"priority",labelI18n:"Priority",placeholderI18n:"0"}],actions:[{key:"run",labelI18n:"Run agent",op:{name:"agent.run",version:"1.0.0"}}],policy:{flags:[],pii:["prompt"]}});

package/dist/node/agent/forms/index.js

@@ -0,0 +1 @@
+export*from"./agentRun.form.js";

package/dist/node/agent/graph-conversation.js

@@ -0,0 +1,19 @@
+export const GRAPH_CONVERSATION_DEFAULT_CAPACITY=20,GRAPH_CONVERSATION_MAX_CAPACITY=50,GRAPH_AGENT_DEFAULT_OPS=[{key:"graph.search",version:"1.0.0"},{key:"graph.filter",version:"1.0.0"},{key:"graph.cluster",version:"1.0.0"},{key:"graph.suggest",version:"1.0.0"},{key:"graph.edit",version:"1.0.0"},{key:"graph.refactor",version:"1.0.0"},{key:"graph.compose",version:"1.0.0"},{key:"graph.suggest_evolution",version:"1.0.0"}];const e=["automation","agent","execution","graph","ai","conversation","m5"];export const AiTurnStateDocBlock={id:"docs.tech.agent.ai-turn-state",title:"AiTurnState — LLM turn discriminated union",summary:"Discriminated union for every LLM conversation turn: system | user | assistant | tool-call | tool-result.",kind:"reference",visibility:"public",route:"/docs/tech/agent/ai-turn-state",tags:e,domain:"agent",owners:["platform.ai"],stability:"beta",body:"# AiTurnState\n\nDiscriminated union covering all LLM conversation turn types. Discriminant: `role`.\n\n## Variants\n\n| role | purpose |\n|------|---------|\n| `system` | System-level instruction (persona, capability context) |\n| `user` | User message text |\n| `assistant` | LLM response, optionally carrying `toolCalls` |\n| `tool-call` | Tool invocation request from the LLM |\n| `tool-result` | Result returned by the tool handler |\n\n## Correlation\n\n`tool-call` and `tool-result` turns are linked by `toolCallId`.\n"},GraphConversationDocBlock={id:"docs.tech.agent.graph-conversation",title:"GraphConversation — AI session history buffer",summary:"Ordered turn history + capacity ceiling for AI graph agent sessions. Session identity via sessionId.",kind:"reference",visibility:"public",route:"/docs/tech/agent/graph-conversation",tags:e,domain:"agent",owners:["platform.ai"],stability:"beta",body:`# GraphConversation
+
+Session history buffer for the AI graph agent. Holds up to \`capacity\` turns
+(default ${GRAPH_CONVERSATION_DEFAULT_CAPACITY}, max ${GRAPH_CONVERSATION_MAX_CAPACITY}).
+
+## Cost alignment
+
+Capacity is bounded to keep context-window token costs within the per-session
+$0.50 ceiling defined in \`m3-p0-ai-cost-ceiling.md\`.
+
+## Fields
+
+| field | description |
+|-------|-------------|
+| \`sessionId\` | Stable session identifier |
+| \`history\` | Ordered AiTurnState array (oldest first) |
+| \`capacity\` | Max retained turns before eviction |
+| \`createdAt\` | ISO 8601 timestamp when the session was created |
+`},AiAgentEditorDocBlock={id:"docs.tech.agent.ai-agent-editor",title:"AiAgentEditor — graph editing session contract",summary:"Composes GraphConversation with graphOps capability refs for the AiPairPanel editing session.",kind:"reference",visibility:"public",route:"/docs/tech/agent/ai-agent-editor",tags:e,domain:"agent",owners:["platform.ai"],stability:"beta",body:"# AiAgentEditor\n\nSession contract that wires a `GraphConversation` to the set of graph\noperations available to the AI agent in this editing context.\n\n## Key invariants\n\n- `autoCommit` must default to `false` (W7.4 suggestion-confirmation UX)\n- `availableOps` defaults to all graphOps + `graph.edit`\n- `contextGraphId` matches the `contextGraphId` accepted by all graphOps commands\n\n## Composition\n\n`AiAgentEditor` is the session state held by `AiPairPanel` (M5 P3/W3.1).\nEach user interaction advances `conversation.history` and may trigger one or\nmore graphOps/edit tool calls.\n"};

package/dist/node/agent/index.js

@@ -0,0 +1 @@
+export*from"./agent.feature.js";export*from"./capabilities/index.js";export*from"./commands/index.js";export*from"./constants.js";export*from"./contracts.js";export*from"./events/index.js";export*from"./forms/index.js";export*from"./graph-conversation.js";export*from"./presentations/index.js";export*from"./protocol/index.js";export*from"./queries/index.js";export*from"./registry.js";export*from"./runner.js";export*from"./spec.js";export*from"./task-tree.js";export*from"./views/index.js";

package/dist/node/agent/presentations/agentRunAudit.presentation.js

@@ -0,0 +1,4 @@
+import{docId as t}from"../../docs/registry.js";import{definePresentation as e}from"../../presentations/index.js";import{AGENT_DOMAIN as n,AGENT_OWNERS as o,AGENT_STABILITY as a,AGENT_TAGS as i}from"../constants.js";export const AgentRunAuditDocBlock={id:"docs.tech.agent.run.audit",title:"Agent run audit presentation",summary:"Presentation spec for agent run audit views.",kind:"reference",visibility:"public",route:"/docs/tech/agent/run/audit",tags:["agent","presentation","audit"],body:`# agent.run.audit
+
+Presentation surface used to inspect run provenance, tools, approvals, and outputs.
+`},AgentRunAuditPresentation=e({meta:{key:"agent.run.audit",title:"Agent Run Audit",version:"1.0.0",description:"Audit layout for agent runs and artifacts.",goal:"Explain run provenance, tools, approvals, and outputs.",context:"Used by Studio to inspect agent run audit trails.",domain:n,owners:o,tags:[...i,"audit"],stability:a,docId:[t("docs.tech.agent.run.audit")]},capability:{key:"agent.execution",version:"1.0.0"},source:{type:"component",framework:"react",componentKey:"agentRunAudit"},targets:["react","markdown"]});

package/dist/node/agent/presentations/index.js

@@ -0,0 +1 @@
+export*from"./agentRunAudit.presentation.js";

package/dist/node/agent/protocol/application-signature.js

@@ -0,0 +1 @@
+import{sha256Hex as n}from"@lssm/lib.crypto-utils";import{z as e}from"zod";import{canonicalJsonString as r}from"../../rich-reference/canonical-serializer.js";import{agentProtocolDigestSchema as a,agentProtocolRefSchema as i,agentProtocolReleaseShaSchema as o,agentProtocolTimestampSchema as p}from"./common.js";export const AGENT_APPLICATION_SIGNATURE_V1="contractspec.agent.application-signature.v1",agentApplicationSignatureMaterialV1Schema=e.object({schemaVersion:e.literal(AGENT_APPLICATION_SIGNATURE_V1),signatureRef:i,keyRef:i,trustPolicyRef:i,publisherRef:i,publisherClass:e.literal("first_party"),applicationId:i,applicationVersion:i,manifestDigest:a,permissionSummaryDigest:a,sourceDigest:a,releaseSha:o,signedAt:p}).strict(),agentApplicationSignatureV1Schema=e.object({material:agentApplicationSignatureMaterialV1Schema,materialDigest:a,algorithm:e.literal("ed25519"),signatureBase64:e.string().regex(/^[A-Za-z0-9+/]+={0,2}$/).min(80).max(100)}).strict();export function digestAgentApplicationSignatureMaterialV1(t){return`sha256:${n(r(t))}`}export function applicationSignatureMessageV1(t){return new TextEncoder().encode(digestAgentApplicationSignatureMaterialV1(t))}export function digestAgentApplicationSignatureV1(t){return`sha256:${n(r(t))}`}export function verifyAgentApplicationSignatureDigestV1(t){return t.materialDigest===digestAgentApplicationSignatureMaterialV1(t.material)}

package/dist/node/agent/protocol/application.js

@@ -0,0 +1,4 @@
+import{sha256Hex as c}from"@lssm/lib.crypto-utils";import{z as t}from"zod";import{canonicalJsonString as p}from"../../rich-reference/canonical-serializer.js";import{agentProtocolDigestSchema as r,agentProtocolRefSchema as e,agentProtocolTimestampSchema as s}from"./common.js";function a(o,n){if(new Set(o).size!==o.length)n.addIssue({code:t.ZodIssueCode.custom,message:"Reference sets must not contain duplicates"})}export const AGENT_PROTOCOL_CONFIG_V1="contractspec.agent.protocol-config.v1",AGENT_APPLICATION_MANIFEST_V1="contractspec.agent.application-manifest.v1",AGENT_APPLICATION_PERMISSION_SUMMARY_V1="contractspec.agent.application-permission-summary.v1",AGENT_COMMUNICATION_BINDING_V1="contractspec.agent.communication-binding.v1",AGENT_CONNECTION_REQUIREMENT_V1="contractspec.agent.connection-requirement.v1",AGENT_AUTOMATION_BINDING_V1="contractspec.agent.automation-binding.v1",AgentProtocolV1DocBlock={id:"docs.tech.agent.protocol-v1",title:"Agent protocol V1",summary:"Portable Plan–Act–Reflect contracts with deterministic authority.",kind:"reference",visibility:"public",route:"/docs/tech/agent/protocol-v1",tags:["agent","protocol","plan-act-reflect"],body:`# Agent protocol V1
+
+The protocol describes durable context, plans, checkpoints, reflections, help, delegation, model routes, and evidence. It does not execute tools, grant authority, deliver messages, schedule work, or persist runtime state. External effects remain authorized by Connect and performed by Runtime Nodes.
+`},agentProtocolConfigV1Schema=t.object({schemaVersion:t.literal(AGENT_PROTOCOL_CONFIG_V1),reasoningMode:t.literal("plan_act_reflect"),contextPolicyRef:e,planPolicyRef:e,reflectionPolicyRef:e,helpPolicyRef:e,teamPolicyRef:e,modelPolicyRef:e,budgetPolicyRef:e,memoryMode:t.literal("proposal_only")}).strict(),agentApplicationPermissionSummaryV1Schema=t.object({schemaVersion:t.literal(AGENT_APPLICATION_PERMISSION_SUMMARY_V1),id:e,toolRefs:t.array(e),approvalRequiredToolRefs:t.array(e),connectionRequirementRefs:t.array(e),communicationBindingRefs:t.array(e),automationBindingRefs:t.array(e),subagentRefs:t.array(e),evaluationRefs:t.array(e),summaryDigest:r}).strict().superRefine((o,n)=>{for(const i of["toolRefs","approvalRequiredToolRefs","connectionRequirementRefs","communicationBindingRefs","automationBindingRefs","subagentRefs","evaluationRefs"])a(o[i],n);for(const i of o.approvalRequiredToolRefs)if(!o.toolRefs.includes(i))n.addIssue({code:t.ZodIssueCode.custom,path:["approvalRequiredToolRefs"],message:`Approval tool is not declared: ${i}`})}),agentCommunicationBindingV1Schema=t.object({schemaVersion:t.literal(AGENT_COMMUNICATION_BINDING_V1),profileRef:e,conversationRef:e.optional(),ingressRef:e.optional(),deliveryIntentRef:e.optional(),progressDestinationRef:e.optional()}).strict(),agentConnectionRequirementV1Schema=t.object({schemaVersion:t.literal(AGENT_CONNECTION_REQUIREMENT_V1),connectionProfileRef:e,capabilityRef:e,grantRequirementRefs:t.array(e).min(1),directions:t.array(t.enum(["inbound","outbound","read","write"])).min(1)}).strict().superRefine((o,n)=>{a(o.grantRequirementRefs,n);a(o.directions,n)}),agentAutomationBindingV1Schema=t.object({schemaVersion:t.literal(AGENT_AUTOMATION_BINDING_V1),automationRef:e,automationVersion:e,workflowRef:e,triggerRef:e,parameterBindingRefs:t.array(e),policyRefs:t.array(e).min(1),expectedEvidenceRefs:t.array(e).min(1),deliveryIntentRef:e.optional(),expiresAt:s.optional()}).strict().superRefine((o,n)=>{a(o.parameterBindingRefs,n);a(o.policyRefs,n);a(o.expectedEvidenceRefs,n)}),agentApplicationManifestV1Schema=t.object({schemaVersion:t.literal(AGENT_APPLICATION_MANIFEST_V1),applicationId:e,applicationVersion:e,agentRef:e,sourceDigest:r,protocol:agentProtocolConfigV1Schema,toolRefs:t.array(e),connectionRequirementRefs:t.array(e),communicationBindingRefs:t.array(e),automationBindingRefs:t.array(e),permissionSummaryRef:e,compiledAt:s,manifestDigest:r}).strict().superRefine((o,n)=>{for(const i of["toolRefs","connectionRequirementRefs","communicationBindingRefs","automationBindingRefs"])if(new Set(o[i]).size!==o[i].length)n.addIssue({code:t.ZodIssueCode.custom,path:[i],message:`${i} must not contain duplicates`})});export function digestAgentApplicationManifestV1(o){return digestAgentApplicationValueV1(o)}export function digestAgentApplicationPermissionSummaryV1(o){return digestAgentApplicationValueV1(o)}export function verifyAgentApplicationManifestV1(o){const{manifestDigest:n,...i}=o;return n===digestAgentApplicationManifestV1(i)}export function verifyAgentApplicationPermissionSummaryV1(o){const{summaryDigest:n,...i}=o;return n===digestAgentApplicationPermissionSummaryV1(i)}export function digestAgentApplicationValueV1(o){return`sha256:${c(p(o))}`}export*from"./application-signature.js";

package/dist/node/agent/protocol/automation/automation.test-fixture.js

@@ -0,0 +1 @@
+import{AGENT_AUTOMATION_DEFINITION_V1 as t,AGENT_AUTOMATION_PREVIEW_V1 as a,agentAutomationDefinitionV1Schema as o,agentAutomationPreviewV1Schema as n}from"./contracts.js";import{digestAgentAutomationDefinitionV1 as r,digestAgentAutomationMaterializationV1 as s,digestAgentAutomationPreviewV1 as c,digestAgentAutomationStateV1 as p}from"./digests.js";import{AGENT_AUTOMATION_MATERIALIZATION_V1 as d,AGENT_AUTOMATION_STATE_V1 as l,agentAutomationMaterializationV1Schema as m,agentAutomationStateV1Schema as f}from"./lifecycle.js";export const now="2026-08-14T08:00:00Z",next="2026-08-15T08:00:00Z",expiry="2026-08-21T08:00:00Z",digest=`sha256:${"a".repeat(64)}`,scope={tenantId:"tenant.1",spaceId:"space.1",productKey:"companyos",applicationRef:"release-steward",purpose:"release-operations",sessionId:"session.1"},evidence=[{id:"evidence.1",kind:"source_message",ref:"message.1",sourcePackage:"@lssm/lib.communication-spec",timestamp:now,redactionStatus:"redacted"}];export function automationDefinition(){const e={schemaVersion:t,id:"weekday-review",version:"1.0.0",application:{ref:"release-steward",digest},sourceScheduleRef:"weekday-review",target:{kind:"agent",ref:"release-steward",objectiveRef:"objective.review-release"},defaultTrigger:{kind:"cron",expression:"0 8 * * 1-5",timezone:"Europe/Paris"},userConfigurableTrigger:!1,allowedDeliveryChannelRefs:["in-app"],deliveryRequired:!0,policyRefs:["policy.automation"],expectedEvidenceRefs:["evidence.release-report"],effectCapabilityRefs:[],riskTier:"R1",maxRuns:5,maximumActiveDays:7,effectAuthority:"none"};return o.parse({...e,definitionDigest:r(e)})}export function automationPreview(){const e=automationDefinition(),i={schemaVersion:a,id:"preview.weekday-review.1",automationRef:"automation.weekday-review.1",scope,definition:{ref:e.id,digest:e.definitionDigest},application:e.application,sourceConversation:{ref:"conversation.1",digest},sourceInstruction:{ref:"message.1",digest},objectiveSummary:"Review the release every weekday morning.",parameterBindings:[],trigger:e.defaultTrigger,deliveryChannelRef:"in-app",deliveryProfile:{ref:"profile.1",digest},policyRefs:e.policyRefs,expectedEvidenceRefs:e.expectedEvidenceRefs,riskTier:e.riskTier,approvalRequired:!1,status:"preview_only",effectAuthority:"none",createdAt:now,expiresAt:expiry,evidence};return n.parse({...i,previewDigest:c(i)})}export function automationMaterialization(){const e=automationPreview(),i={schemaVersion:d,id:e.automationRef,scope,preview:{ref:e.id,digest:e.previewDigest},definition:e.definition,application:e.application,installation:{ref:"installation.1",digest},installationRevision:3,authorityDecision:{ref:"authority.materialize.1",digest},policyDecisions:[{ref:"policy.automation",digest}],canonicalConversation:e.sourceConversation,trigger:e.trigger,parameterBindings:e.parameterBindings,deliveryChannelRef:e.deliveryChannelRef,deliveryProfile:e.deliveryProfile,initialState:"active",materializedAt:now,expiresAt:e.expiresAt,effectAuthority:"none"};return m.parse({...i,materializationDigest:s(i)})}export function automationState(){const e=automationMaterialization(),i={schemaVersion:l,id:e.id,scope,materialization:{ref:e.id,digest:e.materializationDigest},revision:1,status:"active",nextRunAt:next,runCount:0,updatedAt:now};return f.parse({...i,stateDigest:p(i)})}

package/dist/node/agent/protocol/automation/contracts.js

@@ -0,0 +1,4 @@
+import{z as e}from"zod";import{agentArtifactBindingV1Schema as i,agentProtocolDigestSchema as c,agentProtocolEvidencePointerSchema as m,agentProtocolRefSchema as o,agentProtocolTimestampSchema as s,agentRiskTierV1Schema as l,agentScopeV1Schema as d}from"../common.js";export const AGENT_AUTOMATION_DEFINITION_V1="contractspec.agent.automation-definition.v1",AGENT_AUTOMATION_PREVIEW_V1="contractspec.agent.automation-preview.v1",AgentAutomationProtocolV1DocBlock={id:"docs.tech.agent.automation-protocol-v1",title:"Governed agent automation protocol V1",summary:"Immutable previews, materializations, claims, receipts, and follow-ups for bounded durable automation.",kind:"reference",visibility:"public",route:"/docs/tech/agent/automation-protocol-v1",tags:["agent","automation","scheduling","durability"],body:`# Governed agent automation protocol V1
+
+Protocol V1 maps a user preview onto one qualified application schedule, then binds materialization, lifecycle state, exact occurrence claims, durable run receipts, and CommunicationOS follow-ups by scope and digest. Every artifact carries \`effectAuthority: "none"\`. Agent Host owns scheduling and recovery, injected policy ports own authority, CommunicationOS owns delivery admission and fallback, and Runtime Nodes remain the only external-effect executors.
+`};const u=e.string().trim().regex(/^\S+\s+\S+\s+\S+\s+\S+\s+\S+$/);export const agentAutomationTriggerV1Schema=e.discriminatedUnion("kind",[e.object({kind:e.literal("cron"),expression:u,timezone:o}).strict(),e.object({kind:e.literal("once"),runAt:s}).strict()]),agentAutomationTargetV1Schema=e.object({kind:e.enum(["agent","subagent","workflow"]),ref:o,objectiveRef:o}).strict(),agentAutomationParameterBindingV1Schema=e.object({key:o,value:i}).strict(),agentAutomationDefinitionV1Schema=e.object({schemaVersion:e.literal(AGENT_AUTOMATION_DEFINITION_V1),id:o,version:o,application:i,sourceScheduleRef:o,target:agentAutomationTargetV1Schema,defaultTrigger:agentAutomationTriggerV1Schema,userConfigurableTrigger:e.boolean(),allowedDeliveryChannelRefs:e.array(o),deliveryRequired:e.boolean(),policyRefs:e.array(o).min(1),expectedEvidenceRefs:e.array(o).min(1),effectCapabilityRefs:e.array(o),riskTier:l,approvalRequirementRef:o.optional(),maxRuns:e.number().int().positive(),maximumActiveDays:e.number().int().positive(),effectAuthority:e.literal("none"),definitionDigest:c}).strict().superRefine((t,a)=>{n(t.allowedDeliveryChannelRefs,"allowedDeliveryChannelRefs",a);n(t.policyRefs,"policyRefs",a);n(t.expectedEvidenceRefs,"expectedEvidenceRefs",a);n(t.effectCapabilityRefs,"effectCapabilityRefs",a);if((t.riskTier==="R2"||t.riskTier==="R3")&&!t.approvalRequirementRef)a.addIssue({code:e.ZodIssueCode.custom,path:["approvalRequirementRef"],message:"R2 and R3 automations require exact effect approval"});if(t.deliveryRequired&&t.allowedDeliveryChannelRefs.length===0)a.addIssue({code:e.ZodIssueCode.custom,path:["allowedDeliveryChannelRefs"],message:"Required delivery needs at least one qualified channel"})}),agentAutomationPreviewV1Schema=e.object({schemaVersion:e.literal(AGENT_AUTOMATION_PREVIEW_V1),id:o,automationRef:o,scope:d,definition:i,application:i,sourceConversation:i,sourceInstruction:i,objectiveSummary:e.string().trim().min(1).max(2000),parameterBindings:e.array(agentAutomationParameterBindingV1Schema),trigger:agentAutomationTriggerV1Schema,deliveryChannelRef:o.optional(),deliveryProfile:i.optional(),policyRefs:e.array(o).min(1),expectedEvidenceRefs:e.array(o).min(1),riskTier:l,approvalRequired:e.boolean(),status:e.literal("preview_only"),effectAuthority:e.literal("none"),createdAt:s,expiresAt:s,evidence:e.array(m).min(1),previewDigest:c}).strict().superRefine((t,a)=>{n(t.parameterBindings.map(({key:r})=>r),"parameterBindings",a);n(t.policyRefs,"policyRefs",a);n(t.expectedEvidenceRefs,"expectedEvidenceRefs",a);if(Date.parse(t.expiresAt)<=Date.parse(t.createdAt))a.addIssue({code:e.ZodIssueCode.custom,path:["expiresAt"],message:"Automation preview must expire after creation"});if(Boolean(t.deliveryChannelRef)!==Boolean(t.deliveryProfile))a.addIssue({code:e.ZodIssueCode.custom,path:["deliveryProfile"],message:"Delivery channel and profile must be selected together"})});function n(t,a,r){if(new Set(t).size!==t.length)r.addIssue({code:e.ZodIssueCode.custom,path:[a],message:`${a} must be unique`})}

package/dist/node/agent/protocol/automation/definition-validation.js

@@ -0,0 +1 @@
+import{validateAgentScopeExactV1 as s}from"../common.js";import{verifyAgentAutomationDigestV1 as r}from"./digests.js";export function validateAgentAutomationPreviewV1(n){const{definition:i,preview:e}=n,t=[];if(!r(i,"definitionDigest"))t.push("Automation definition digest is invalid");if(!r(e,"previewDigest"))t.push("Automation preview digest is invalid");if(e.definition.ref!==i.id||e.definition.digest!==i.definitionDigest)t.push("Automation preview definition binding does not match");if(e.application.ref!==i.application.ref||e.application.digest!==i.application.digest||e.scope.applicationRef!==i.application.ref)t.push("Automation preview application binding does not match");if(!i.userConfigurableTrigger&&JSON.stringify(e.trigger)!==JSON.stringify(i.defaultTrigger))t.push("Automation preview changes a fixed trigger");if(e.deliveryChannelRef&&!i.allowedDeliveryChannelRefs.includes(e.deliveryChannelRef))t.push("Automation preview selects an unqualified delivery channel");if(i.deliveryRequired&&!e.deliveryProfile)t.push("Automation preview is missing required delivery");if(!o(e.policyRefs,i.policyRefs))t.push("Automation preview policy set does not match");if(!o(e.expectedEvidenceRefs,i.expectedEvidenceRefs))t.push("Automation preview evidence requirements do not match");if(e.riskTier!==i.riskTier)t.push("Automation preview changes the qualified risk tier");if(e.approvalRequired!==Boolean(i.approvalRequirementRef))t.push("Automation preview approval requirement does not match");const a=Date.parse(e.createdAt)+i.maximumActiveDays*86400000;if(Date.parse(e.expiresAt)>a)t.push("Automation preview exceeds its maximum active horizon");if(e.trigger.kind==="once"&&(Date.parse(e.trigger.runAt)<Date.parse(e.createdAt)||Date.parse(e.trigger.runAt)>Date.parse(e.expiresAt)))t.push("Automation one-shot trigger is outside the preview window");return[...new Set(t)]}function o(n,i){return JSON.stringify([...n].sort())===JSON.stringify([...i].sort())}export function validateAgentAutomationPreviewScopeV1(n){return s({expected:n.expected,observed:n.preview.scope})}

package/dist/node/agent/protocol/automation/digests.js

@@ -0,0 +1 @@
+import{sha256Hex as a}from"@lssm/lib.crypto-utils";import{canonicalJsonString as g}from"../../../rich-reference/canonical-serializer.js";function i(t){return`sha256:${a(g(t))}`}export const digestAgentAutomationDefinitionV1=(t)=>i(t),digestAgentAutomationPreviewV1=(t)=>i(t),digestAgentAutomationMaterializationV1=(t)=>i(t),digestAgentAutomationStateV1=(t)=>i(t),digestAgentAutomationTransitionV1=(t)=>i(t),digestAgentAutomationClaimV1=(t)=>i(t),digestAgentAutomationRunReceiptV1=(t)=>i(t),digestAgentAutomationFollowUpV1=(t)=>i(t);export function verifyAgentAutomationDigestV1(t,o){const{[o]:e,...n}=t;return e===i(n)}

package/dist/node/agent/protocol/automation/index.js

@@ -0,0 +1 @@
+export*from"./contracts.js";export*from"./digests.js";export*from"./lifecycle.js";export*from"./validation.js";

package/dist/node/agent/protocol/automation/lifecycle-validation.js

@@ -0,0 +1 @@
+import{validateAgentScopeExactV1 as r}from"../common.js";import{verifyAgentAutomationDigestV1 as s}from"./digests.js";export function validateAgentAutomationMaterializationV1(o){const{preview:e,materialization:t}=o,i=r({expected:e.scope,observed:t.scope});for(const[a,n,u]of[[e,"previewDigest","preview"],[t,"materializationDigest","materialization"]])if(!s(a,n))i.push(`Automation ${u} digest is invalid`);if(t.id!==e.automationRef||t.preview.ref!==e.id||t.preview.digest!==e.previewDigest)i.push("Automation materialization preview binding does not match");for(const a of["definition","application"])if(t[a].ref!==e[a].ref||t[a].digest!==e[a].digest)i.push(`Automation materialization ${a} binding does not match`);if(t.canonicalConversation.ref!==e.sourceConversation.ref||t.canonicalConversation.digest!==e.sourceConversation.digest)i.push("Automation materialization conversation binding does not match");if(JSON.stringify(t.trigger)!==JSON.stringify(e.trigger)||JSON.stringify(t.parameterBindings)!==JSON.stringify(e.parameterBindings)||t.deliveryChannelRef!==e.deliveryChannelRef||JSON.stringify(t.deliveryProfile)!==JSON.stringify(e.deliveryProfile))i.push("Automation materialization changes previewed behavior");if(JSON.stringify(t.policyDecisions.map(({ref:a})=>a).sort())!==JSON.stringify([...e.policyRefs].sort()))i.push("Automation materialization policy decisions do not match");if(Date.parse(t.materializedAt)<Date.parse(e.createdAt)||Date.parse(t.materializedAt)>Date.parse(e.expiresAt)||Date.parse(t.expiresAt)>Date.parse(e.expiresAt))i.push("Automation materialization is outside the preview window");return[...new Set(i)]}export function validateAgentAutomationStateV1(o){const{materialization:e,state:t}=o,i=r({expected:e.scope,observed:t.scope});if(!s(e,"materializationDigest"))i.push("Automation materialization digest is invalid");if(!s(t,"stateDigest"))i.push("Automation state digest is invalid");if(t.id!==e.id||t.materialization.ref!==e.id||t.materialization.digest!==e.materializationDigest)i.push("Automation state materialization binding does not match");if(Date.parse(t.updatedAt)<Date.parse(e.materializedAt))i.push("Automation state predates materialization");if(t.nextRunAt&&Date.parse(t.nextRunAt)>Date.parse(e.expiresAt))i.push("Automation state schedules work after expiry");return[...new Set(i)]}const c={pause:["active","paused"],resume:["paused","active"],revoke:["active|paused","revoked"],expire:["active|paused","expired"]};export function validateAgentAutomationTransitionV1(o){const{materialization:e,from:t,to:i,transition:a}=o,n=[...validateAgentAutomationStateV1({materialization:e,state:t}),...validateAgentAutomationStateV1({materialization:e,state:i}),...r({expected:e.scope,observed:a.scope})];if(!s(a,"receiptDigest"))n.push("Automation transition digest is invalid");if(a.automationRef!==t.id||a.fromState.ref!==t.id||a.fromState.digest!==t.stateDigest||a.toState.ref!==i.id||a.toState.digest!==i.stateDigest)n.push("Automation transition state binding does not match");if(i.id!==t.id||i.revision!==t.revision+1||i.materialization.digest!==t.materialization.digest||i.runCount!==t.runCount||JSON.stringify(i.activeClaim)!==JSON.stringify(t.activeClaim)||JSON.stringify(i.lastRunReceipt)!==JSON.stringify(t.lastRunReceipt))n.push("Automation transition changes protected runtime state");const[u,m]=c[a.action];if(!u.split("|").includes(t.status)||i.status!==m)n.push("Automation lifecycle transition is invalid");if(["pause","resume"].includes(a.action)){if(i.nextRunAt!==t.nextRunAt)n.push("Pause or resume changes the next occurrence")}else if(t.activeClaim)n.push("Automation with active work cannot become terminal");if(a.action==="expire"&&Date.parse(a.transitionedAt)<Date.parse(e.expiresAt))n.push("Automation cannot expire before its materialized expiry");return[...new Set(n)]}export function validateAgentAutomationClaimV1(o){const{materialization:e,state:t,claim:i}=o,a=validateAgentAutomationStateV1({materialization:e,state:t});a.push(...r({expected:e.scope,observed:i.scope}));if(!s(i,"claimDigest"))a.push("Automation claim digest is invalid");if(t.status!=="active"||t.activeClaim||i.automationRef!==t.id||i.materialization.ref!==e.id||i.materialization.digest!==e.materializationDigest||i.state.ref!==t.id||i.state.digest!==t.stateDigest||i.stateRevision!==t.revision)a.push("Automation claim is not bound to runnable state");if(i.scheduledFor!==t.nextRunAt||Date.parse(i.claimedAt)<Date.parse(i.scheduledFor)||Date.parse(i.claimedAt)>Date.parse(e.expiresAt))a.push("Automation claim is outside its scheduled window");if(i.canonicalConversation.ref!==e.canonicalConversation.ref||i.canonicalConversation.digest!==e.canonicalConversation.digest)a.push("Automation claim conversation binding does not match");return[...new Set(a)]}export function validateAgentAutomationClaimStateV1(o){const{materialization:e,prior:t,current:i,claim:a}=o,n=[...validateAgentAutomationClaimV1({materialization:e,state:t,claim:a}),...validateAgentAutomationStateV1({materialization:e,state:i})];if(i.revision!==t.revision+1||i.status!==t.status||i.nextRunAt!==t.nextRunAt||i.runCount!==t.runCount||JSON.stringify(i.lastRunReceipt)!==JSON.stringify(t.lastRunReceipt)||i.activeClaim?.ref!==a.id||i.activeClaim?.digest!==a.claimDigest)n.push("Automation claim state transition is invalid");if(Date.parse(i.updatedAt)<Date.parse(a.claimedAt))n.push("Automation claim state predates its claim");return[...new Set(n)]}

package/dist/node/agent/protocol/automation/lifecycle.js

@@ -0,0 +1 @@
+import{z as e}from"zod";import{agentArtifactBindingV1Schema as t,agentProtocolDigestSchema as r,agentProtocolEvidencePointerSchema as c,agentProtocolRefSchema as i,agentProtocolTimestampSchema as a,agentScopeV1Schema as s}from"../common.js";import{agentAutomationParameterBindingV1Schema as m,agentAutomationTriggerV1Schema as p}from"./contracts.js";export const AGENT_AUTOMATION_MATERIALIZATION_V1="contractspec.agent.automation-materialization.v1",AGENT_AUTOMATION_STATE_V1="contractspec.agent.automation-state.v1",AGENT_AUTOMATION_TRANSITION_V1="contractspec.agent.automation-transition.v1",AGENT_AUTOMATION_CLAIM_V1="contractspec.agent.automation-claim.v1",AGENT_AUTOMATION_RUN_RECEIPT_V1="contractspec.agent.automation-run-receipt.v1",AGENT_AUTOMATION_FOLLOW_UP_V1="contractspec.agent.automation-follow-up.v1",agentAutomationMaterializationV1Schema=e.object({schemaVersion:e.literal(AGENT_AUTOMATION_MATERIALIZATION_V1),id:i,scope:s,preview:t,definition:t,application:t,installation:t,installationRevision:e.number().int().positive(),authorityDecision:t,policyDecisions:e.array(t).min(1),canonicalConversation:t,trigger:p,parameterBindings:e.array(m),deliveryChannelRef:i.optional(),deliveryProfile:t.optional(),initialState:e.enum(["active","paused"]),materializedAt:a,expiresAt:a,effectAuthority:e.literal("none"),materializationDigest:r}).strict().superRefine((o,n)=>{if(Date.parse(o.expiresAt)<=Date.parse(o.materializedAt))n.addIssue({code:e.ZodIssueCode.custom,path:["expiresAt"],message:"Automation materialization must expire after activation"});if(Boolean(o.deliveryChannelRef)!==Boolean(o.deliveryProfile))n.addIssue({code:e.ZodIssueCode.custom,path:["deliveryProfile"],message:"Delivery channel and profile must be selected together"})}),agentAutomationStateV1Schema=e.object({schemaVersion:e.literal(AGENT_AUTOMATION_STATE_V1),id:i,scope:s,materialization:t,revision:e.number().int().positive(),status:e.enum(["active","paused","expired","revoked","completed","reconciliation_required"]),nextRunAt:a.optional(),runCount:e.number().int().nonnegative(),activeClaim:t.optional(),lastRunReceipt:t.optional(),updatedAt:a,stateDigest:r}).strict().superRefine((o,n)=>{if(["expired","revoked","completed"].includes(o.status)&&(o.nextRunAt||o.activeClaim))n.addIssue({code:e.ZodIssueCode.custom,path:["status"],message:"Terminal automation state cannot retain future or active work"});if((o.status==="active"||o.status==="paused")&&!o.nextRunAt)n.addIssue({code:e.ZodIssueCode.custom,path:["nextRunAt"],message:"Runnable automation state requires its next occurrence"});if(o.status==="reconciliation_required"&&!o.activeClaim)n.addIssue({code:e.ZodIssueCode.custom,path:["activeClaim"],message:"Reconciliation state requires the unresolved claim"})}),agentAutomationTransitionV1Schema=e.object({schemaVersion:e.literal(AGENT_AUTOMATION_TRANSITION_V1),id:i,scope:s,automationRef:i,fromState:t,toState:t,action:e.enum(["pause","resume","revoke","expire"]),actorRef:i,authorityDecision:t,idempotencyKey:i,evidence:e.array(c).min(1),transitionedAt:a,receiptDigest:r}).strict(),agentAutomationClaimV1Schema=e.object({schemaVersion:e.literal(AGENT_AUTOMATION_CLAIM_V1),id:i,scope:s,automationRef:i,materialization:t,state:t,stateRevision:e.number().int().positive(),occurrenceRef:i,runRef:i,canonicalConversation:t,scheduledFor:a,claimedAt:a,leaseExpiresAt:a,idempotencyKey:i,authorityDecision:t,evidence:e.array(c).min(1),effectAuthority:e.literal("none"),claimDigest:r}).strict().superRefine((o,n)=>{if(Date.parse(o.leaseExpiresAt)<=Date.parse(o.claimedAt))n.addIssue({code:e.ZodIssueCode.custom,path:["leaseExpiresAt"],message:"Automation claim lease must expire after claim time"})}),agentAutomationRunReceiptV1Schema=e.object({schemaVersion:e.literal(AGENT_AUTOMATION_RUN_RECEIPT_V1),id:i,scope:s,claim:t,run:t,terminalDecision:t,outcome:e.enum(["completed","blocked","failed","cancelled","indeterminate"]),evidence:e.array(c).min(1),completedAt:a,receiptDigest:r}).strict(),agentAutomationFollowUpV1Schema=e.object({schemaVersion:e.literal(AGENT_AUTOMATION_FOLLOW_UP_V1),id:i,scope:s,automationRef:i,runReceipt:t,canonicalConversation:t,deliveryIntent:t,policyDecision:t,notBefore:a,expiresAt:a,idempotencyKey:i,evidence:e.array(c).min(1),status:e.literal("requested"),effectAuthority:e.literal("none"),followUpDigest:r}).strict().superRefine((o,n)=>{if(Date.parse(o.expiresAt)<=Date.parse(o.notBefore))n.addIssue({code:e.ZodIssueCode.custom,path:["expiresAt"],message:"Automation follow-up must expire after its earliest delivery"})});

package/dist/node/agent/protocol/automation/run-validation.js

@@ -0,0 +1 @@
+import{validateAgentScopeExactV1 as m}from"../common.js";import{verifyAgentAutomationDigestV1 as u}from"./digests.js";import{validateAgentAutomationStateV1 as c}from"./lifecycle-validation.js";export function validateAgentAutomationRunReceiptV1(n){const{claim:i,receipt:e}=n,t=m({expected:i.scope,observed:e.scope});if(!u(i,"claimDigest"))t.push("Automation claim digest is invalid");if(!u(e,"receiptDigest"))t.push("Automation run receipt digest is invalid");if(e.claim.ref!==i.id||e.claim.digest!==i.claimDigest||e.run.ref!==i.runRef)t.push("Automation run receipt claim or run binding does not match");if(Date.parse(e.completedAt)<Date.parse(i.claimedAt))t.push("Automation run receipt predates its claim");return[...new Set(t)]}export function validateAgentAutomationFollowUpV1(n){const{claim:i,receipt:e,followUp:t}=n,o=validateAgentAutomationRunReceiptV1({claim:i,receipt:e});if(!u(t,"followUpDigest"))o.push("Automation follow-up digest is invalid");if(t.automationRef!==i.automationRef||t.runReceipt.ref!==e.id||t.runReceipt.digest!==e.receiptDigest||t.canonicalConversation.ref!==i.canonicalConversation.ref||t.canonicalConversation.digest!==i.canonicalConversation.digest)o.push("Automation follow-up binding does not match");if(e.outcome==="indeterminate"||Date.parse(t.notBefore)<Date.parse(e.completedAt))o.push("Automation follow-up is unsafe for the run outcome");return[...new Set(o)]}export function validateAgentAutomationRunStateV1(n){const{materialization:i,prior:e,current:t,claim:o,receipt:a}=n,r=[...validateAgentAutomationRunReceiptV1({claim:o,receipt:a}),...c({materialization:i,state:e}),...c({materialization:i,state:t})],s=a.outcome==="indeterminate";if(e.activeClaim?.ref!==o.id||e.activeClaim?.digest!==o.claimDigest||t.revision!==e.revision+1||t.lastRunReceipt?.ref!==a.id||t.lastRunReceipt?.digest!==a.receiptDigest||t.runCount!==e.runCount+(s?0:1)||(s?t.status!=="reconciliation_required"||t.activeClaim?.digest!==o.claimDigest:Boolean(t.activeClaim)))r.push("Automation run state transition is invalid");if(Date.parse(t.updatedAt)<Date.parse(a.completedAt))r.push("Automation run state predates its receipt");return[...new Set(r)]}

package/dist/node/agent/protocol/automation/validation.js

@@ -0,0 +1 @@
+export*from"./definition-validation.js";export*from"./lifecycle-validation.js";export*from"./run-validation.js";

package/dist/node/agent/protocol/bindings.js

@@ -0,0 +1 @@
+import{validateAgentModelFallbackOriginV1 as g}from"./model-fallback-validation.js";import{routeBindingMatchesModelCandidateV1 as s,validateAgentModelSelectionBindingV1 as b,validateModelCandidateV1 as c}from"./model-selection-validation.js";export*from"./application.js";export{validateAgentModelSelectionBindingV1,validateModelCandidateV1}from"./model-selection-validation.js";export function validateAgentModelFallbackEquivalenceV1(e){const t=g(e);t.push(...b({plan:e.plan,selection:e.selection,candidate:e.from}).map((i)=>`Fallback source ${i}`));const r=e.consideredCandidates.map((i)=>i.route.id),d=e.decision.consideredRoutes.map((i)=>i.ref);if(new Set(d).size!==d.length)t.push("Fallback considered routes must be unique");for(const[i,n]of e.decision.consideredRoutes.entries()){const o=e.consideredCandidates[i],l=e.eligibility[i];if(!o||!s(n,o))t.push(`Fallback considered route has a stale binding: ${n.ref}`);if(!o||!l||!s(l.route,o)||n.eligibility!==l.status||n.eligibilityEvidence.ref!==l.evidence.ref||n.eligibilityEvidence.digest!==l.evidence.digest)t.push(`Fallback eligibility binding is stale: ${n.ref}`)}if(JSON.stringify(r)!==JSON.stringify(d))t.push("Fallback considered-route order does not match evaluated candidates");const a=e.consideredCandidates.find((i,n)=>e.eligibility[n]?.status==="eligible"&&c({plan:e.plan,selection:e.selection,candidate:i}).length===0);t.push(...c({plan:e.plan,selection:e.selection,candidate:e.to}).map((i)=>`Fallback ${i.replace("Model route","route")}`));if(!a||a.route.id!==e.to.route.id)t.push("Fallback target is not the first eligible considered route");if(e.decision.decision==="allowed"&&t.length>0)t.push("Fallback cannot be allowed when equivalence checks fail");return t}

package/dist/node/agent/protocol/budget.js

@@ -0,0 +1 @@
+import{z as o}from"zod";import{agentProtocolDigestSchema as i,agentProtocolRefSchema as s,agentProtocolTimestampSchema as r,agentScopeV1Schema as d,validateAgentScopeNarrowingV1 as l}from"./common.js";export const AGENT_RUN_BUDGET_V1="contractspec.agent.run-budget.v1";const t=o.number().int().positive(),c=o.number().int().nonnegative();export const agentRunBudgetV1Schema=o.object({schemaVersion:o.literal(AGENT_RUN_BUDGET_V1),id:s,revision:t,runRef:s,scope:d,authorizedByRef:s,authorizedAt:r,supersedesRef:s.optional(),maxInputTokens:t,maxOutputTokens:t,maxModelCalls:t,maxToolCalls:c,maxEffects:c,maxCostMinorUnits:c,costCurrency:o.string().regex(/^[A-Z]{3}$/),maxRetries:c,maxReplans:c,maxConcurrentAgents:t,maxParticipants:t,maxTaskNodes:t,maxDelegationDepth:c,maxStepsBetweenReflections:t.max(10),maxEpochActiveComputeSeconds:t.max(900),maxActiveComputeSeconds:t,maxWallClockSeconds:t,checkpointIntervalSeconds:t,approvalExpirySeconds:t,leaseHeartbeatSeconds:t,humanCheckInConditionRefs:o.array(s).min(1),qualificationRef:s.optional(),budgetDigest:i}).strict().superRefine((e,a)=>{if(e.scope.runId&&e.scope.runId!==e.runRef)a.addIssue({code:o.ZodIssueCode.custom,path:["scope","runId"],message:"Budget scope runId must match its run reference"});if((e.maxConcurrentAgents>4||e.maxParticipants>8||e.maxTaskNodes>32||e.maxDelegationDepth>2||e.maxActiveComputeSeconds>7200||e.maxWallClockSeconds>86400)&&!e.qualificationRef)a.addIssue({code:o.ZodIssueCode.custom,path:["qualificationRef"],message:"Budgets above protocol V1 defaults require qualification"});if(e.checkpointIntervalSeconds>300)a.addIssue({code:o.ZodIssueCode.custom,path:["checkpointIntervalSeconds"],message:"Active work must checkpoint at least every five minutes"})});const m=["maxInputTokens","maxOutputTokens","maxModelCalls","maxToolCalls","maxEffects","maxCostMinorUnits","maxRetries","maxReplans","maxConcurrentAgents","maxParticipants","maxTaskNodes","maxDelegationDepth","maxStepsBetweenReflections","maxEpochActiveComputeSeconds","maxActiveComputeSeconds","maxWallClockSeconds","approvalExpirySeconds"];export function validateAgentChildBudgetV1(e){const a=[];if(e.child.runRef!==e.parent.runRef)a.push("Child budget changes the parent run");if(e.child.costCurrency!==e.parent.costCurrency)a.push("Child budget changes the parent cost currency");a.push(...l({parent:e.parent.scope,child:e.child.scope}).map((n)=>`Child budget ${n.replace("Child scope","scope")}`));for(const n of m)if(e.child[n]>e.parent[n])a.push(`Child budget ${n} exceeds parent budget`);if(e.child.checkpointIntervalSeconds>e.parent.checkpointIntervalSeconds)a.push("Child checkpoint interval is weaker than parent budget");if(e.child.leaseHeartbeatSeconds>e.parent.leaseHeartbeatSeconds)a.push("Child heartbeat interval is weaker than parent budget");for(const n of e.parent.humanCheckInConditionRefs)if(!e.child.humanCheckInConditionRefs.includes(n))a.push(`Child budget drops human check-in condition: ${n}`);return a}

package/dist/node/agent/protocol/common.js

@@ -0,0 +1 @@
+import{z as i}from"zod";import{agentStepEvidencePointerSchema as g}from"../../agent-step-observability/validation.js";export const AGENT_PROTOCOL_V1="contractspec.agent.protocol.v1",agentProtocolRefSchema=i.string().trim().min(1),agentProtocolTimestampSchema=i.string().datetime({offset:!0}),agentProtocolDigestSchema=i.string().regex(/^sha256:[a-f0-9]{64}$/),agentProtocolReleaseShaSchema=i.string().regex(/^[a-f0-9]{40}$/),agentProtocolEvidencePointerSchema=g.extend({timestamp:agentProtocolTimestampSchema,artifactHash:agentProtocolDigestSchema.optional()}).strict(),agentRiskTierV1Schema=i.enum(["R0","R1","R2","R3"]),agentScopeV1Schema=i.object({tenantId:agentProtocolRefSchema,spaceId:agentProtocolRefSchema,productKey:agentProtocolRefSchema,applicationRef:agentProtocolRefSchema,purpose:agentProtocolRefSchema,sessionId:agentProtocolRefSchema.optional(),runId:agentProtocolRefSchema.optional()}).strict(),agentVersionSetV1Schema=i.object({applicationVersion:agentProtocolRefSchema,promptVersion:agentProtocolRefSchema,modelRouteVersion:agentProtocolRefSchema,toolSchemaVersions:i.array(agentProtocolRefSchema),policyVersion:agentProtocolRefSchema,contextCompilerVersion:agentProtocolRefSchema,evaluatorVersion:agentProtocolRefSchema,sandboxDigest:agentProtocolDigestSchema,releaseSha:agentProtocolReleaseShaSchema}).strict(),agentConfidenceV1Schema=i.object({score:i.number().min(0).max(1),calibrationRef:agentProtocolRefSchema,uncertaintyRefs:i.array(agentProtocolRefSchema)}).strict(),agentEffectProposalV1Schema=i.object({id:agentProtocolRefSchema,capabilityRef:agentProtocolRefSchema,operationRef:agentProtocolRefSchema,riskTier:agentRiskTierV1Schema,approvalRequirementRef:agentProtocolRefSchema.optional(),connectDecisionRef:agentProtocolRefSchema.optional(),runtimeWorkOrderRef:agentProtocolRefSchema.optional(),idempotencyRef:agentProtocolRefSchema}).strict().superRefine((e,o)=>{if((e.riskTier==="R2"||e.riskTier==="R3")&&!e.approvalRequirementRef)o.addIssue({code:i.ZodIssueCode.custom,path:["approvalRequirementRef"],message:"R2 and R3 effects require an approval requirement reference"})}),agentCriterionResultV1Schema=i.object({criterionRef:agentProtocolRefSchema,satisfied:i.boolean(),evidenceRefs:i.array(agentProtocolRefSchema)}).strict(),agentArtifactBindingV1Schema=i.object({ref:agentProtocolRefSchema,digest:agentProtocolDigestSchema}).strict(),agentExecutionVerificationBindingV1Schema=i.object({verificationPolicyRef:agentProtocolRefSchema,executionLaneCompletion:agentArtifactBindingV1Schema,verifierSignoff:agentArtifactBindingV1Schema}).strict();const d=["tenantId","spaceId","productKey","applicationRef","purpose"];export function validateAgentScopeNarrowingV1(e){const o=[];for(const t of d)if(e.parent[t]!==e.child[t])o.push(`Child scope changes parent ${t}`);for(const t of["sessionId","runId"]){const r=e.parent[t],a=e.child[t];if(r&&a!==r)o.push(`Child scope removes or changes parent ${t}`)}return o}export function validateAgentScopeExactV1(e){const o=[];for(const t of[...d,"sessionId","runId"])if(e.expected[t]!==e.observed[t])o.push(`Observed scope does not match expected ${t}`);return o}export function validateAgentExecutionVerificationV1(e){if(!e.binding)return["Execution verification binding is missing"];if(!e.canonical)return["Canonical execution verification is missing"];const o=[];if(e.binding.verificationPolicyRef!==e.expectedPolicyRef||e.canonical.verificationPolicyRef!==e.expectedPolicyRef)o.push("Execution verification policy does not match");for(const t of["executionLaneCompletion","verifierSignoff"])if(e.binding[t].ref!==e.canonical[t].ref||e.binding[t].digest!==e.canonical[t].digest)o.push(`Execution verification ${t} binding does not match`);if(e.canonical.status!=="approved")o.push("Canonical execution verification is not approved");return o}export function validateAgentDirectedAcyclicGraph(e,o){const t=[];if(e.length>o)t.push(`Graph has ${e.length} nodes; maximum is ${o}`);const r=new Set;for(const n of e){if(r.has(n.id))t.push(`Duplicate graph node id: ${n.id}`);r.add(n.id)}for(const n of e)for(const c of n.dependsOn){if(!r.has(c))t.push(`Node ${n.id} has unknown dependency: ${c}`);if(c===n.id)t.push(`Node ${n.id} cannot depend on itself`)}const a=new Set,s=new Set,p=new Map(e.map((n)=>[n.id,n])),f=(n)=>{if(a.has(n)){t.push(`Graph contains a dependency cycle at ${n}`);return}if(s.has(n))return;a.add(n);for(const c of p.get(n)?.dependsOn??[])if(p.has(c))f(c);a.delete(n);s.add(n)};for(const n of r)f(n);return[...new Set(t)]}

package/dist/node/agent/protocol/delegation.js

@@ -0,0 +1 @@
+import{z as e}from"zod";import{agentRunBudgetV1Schema as l}from"./budget.js";import{agentArtifactBindingV1Schema as s,agentCriterionResultV1Schema as m,agentExecutionVerificationBindingV1Schema as f,agentProtocolDigestSchema as o,agentProtocolEvidencePointerSchema as c,agentProtocolRefSchema as t,agentProtocolTimestampSchema as n,agentScopeV1Schema as u,validateAgentDirectedAcyclicGraph as g}from"./common.js";export const AGENT_TASK_V1="contractspec.agent.task.v1",AGENT_TASK_GRAPH_PLAN_V1="contractspec.agent.task-graph-plan.v1",AGENT_DELEGATION_V1="contractspec.agent.delegation.v1",AGENT_TASK_RESULT_V1="contractspec.agent.task-result.v1",AGENT_TEAM_SYNTHESIS_V1="contractspec.agent.team-synthesis.v1",agentTaskV1Schema=e.object({schemaVersion:e.literal(AGENT_TASK_V1),id:t,dependsOn:e.array(t),objective:t,contextProjection:s,toolRefs:e.array(t),grantRequirementRefs:e.array(t),budget:s,approvalRequirementRefs:e.array(t),expectedArtifactRefs:e.array(t),requiredEvidenceKinds:e.array(t).min(1),completionCriteria:e.array(t).min(1)}).strict(),agentTaskGraphPlanV1Schema=e.object({schemaVersion:e.literal(AGENT_TASK_GRAPH_PLAN_V1),id:t,revision:e.number().int().positive(),supersedesRef:t.optional(),runRef:t,scope:u,mode:e.enum(["supervisor","coordinated_team"]),leadPrincipalRef:t,participantRefs:e.array(t).max(7),tasks:e.array(agentTaskV1Schema).min(1).max(32),budgetRef:t,verificationPolicyRef:t,createdAt:n,graphDigest:o}).strict().superRefine((a,i)=>{for(const r of g(a.tasks,32))i.addIssue({code:e.ZodIssueCode.custom,path:["tasks"],message:r});if(new Set(a.participantRefs).size!==a.participantRefs.length)i.addIssue({code:e.ZodIssueCode.custom,path:["participantRefs"],message:"Task graph participants must be unique"});if(a.participantRefs.includes(a.leadPrincipalRef))i.addIssue({code:e.ZodIssueCode.custom,path:["participantRefs"],message:"Lead principal must not be repeated as a participant"})}),agentDelegationV1Schema=e.object({schemaVersion:e.literal(AGENT_DELEGATION_V1),id:t,runRef:t,taskGraph:s,taskRef:t,parentPrincipalRef:t,derivedPrincipalRef:t,contextProjection:s,toolRefs:e.array(t),grantBindings:e.array(e.object({requirementRef:t,grantRef:t}).strict()),parentBudget:s,budget:l,delegationDepth:e.number().int().positive(),mayDelegate:e.boolean(),approvalRequirementRefs:e.array(t),timeoutSeconds:e.number().int().positive(),createdAt:n,qualificationRef:t.optional(),delegationDigest:o}).strict().superRefine((a,i)=>{if(a.delegationDepth>2&&!a.qualificationRef)i.addIssue({code:e.ZodIssueCode.custom,path:["qualificationRef"],message:"Delegation deeper than two requires qualification"});if(a.mayDelegate&&a.delegationDepth>=2)i.addIssue({code:e.ZodIssueCode.custom,path:["mayDelegate"],message:"Protocol V1 cannot implicitly delegate beyond depth two"});if(a.timeoutSeconds>a.budget.maxWallClockSeconds)i.addIssue({code:e.ZodIssueCode.custom,path:["timeoutSeconds"],message:"Delegation timeout cannot exceed its child wall-clock budget"})});const d=e.object({claim:t,evidence:e.array(c).min(1)}).strict(),h=e.object({requirementRef:t,evidence:e.array(c).min(1)}).strict();export const agentTaskResultV1Schema=e.object({schemaVersion:e.literal(AGENT_TASK_RESULT_V1),id:t,taskGraph:s,taskRef:t,delegation:s,producerPrincipalRef:t,status:e.enum(["ready_for_verification","blocked","failed","cancelled"]),artifactRefs:e.array(t),claims:e.array(d),evidenceSatisfactions:e.array(h),completionCriteria:e.array(m),uncertaintyRefs:e.array(t),blockingRef:t.optional(),reportedAt:n,resultDigest:o}).strict().superRefine((a,i)=>{if(a.status==="ready_for_verification"&&(a.artifactRefs.length===0||a.claims.length===0||a.evidenceSatisfactions.length===0||a.completionCriteria.length===0))i.addIssue({code:e.ZodIssueCode.custom,path:["status"],message:"Completed tasks require artifacts and evidenced claims"});if(a.status==="blocked"&&!a.blockingRef)i.addIssue({code:e.ZodIssueCode.custom,path:["blockingRef"],message:"Blocked task results require a blocking reference"})});const R=e.object({id:t,resultRefs:e.array(t).min(2),summary:t,resolutionRef:t.optional()}).strict();export const agentTeamSynthesisV1Schema=e.object({schemaVersion:e.literal(AGENT_TEAM_SYNTHESIS_V1),id:t,taskGraph:s,results:e.array(s).min(1),claims:e.array(d).min(1),conflicts:e.array(R),verification:f.optional(),status:e.enum(["ready_for_verification","needs_resolution","verified"]),createdAt:n,synthesisDigest:o}).strict().superRefine((a,i)=>{if(a.conflicts.some((p)=>!p.resolutionRef)&&a.status!=="needs_resolution")i.addIssue({code:e.ZodIssueCode.custom,path:["status"],message:"Unresolved teammate conflicts require needs_resolution"});if(a.status==="verified"&&!a.verification)i.addIssue({code:e.ZodIssueCode.custom,path:["verification"],message:"Verified synthesis requires execution-lane verification"})}),agentTaskGraphV1Schema=agentTaskGraphPlanV1Schema;export{validateAgentDelegationBindingV1,validateAgentTaskResultBindingV1,validateAgentTeamSynthesisBindingV1}from"./graph-validation.js";

package/dist/node/agent/protocol/execution.js

@@ -0,0 +1 @@
+import{z as e}from"zod";import{agentArtifactBindingV1Schema as s,agentCriterionResultV1Schema as p,agentExecutionVerificationBindingV1Schema as m,agentProtocolDigestSchema as c,agentProtocolEvidencePointerSchema as r,agentProtocolRefSchema as o,agentProtocolTimestampSchema as i,agentRiskTierV1Schema as l}from"./common.js";export const AGENT_RUN_EPOCH_V1="contractspec.agent.run-epoch.v1",AGENT_CHECKPOINT_V1="contractspec.agent.checkpoint.v1",AGENT_PROGRESS_V1="contractspec.agent.progress.v1",AGENT_TERMINAL_DECISION_V1="contractspec.agent.terminal-decision.v1",agentRunPhaseV1Schema=e.enum(["received","context_compiled","planned","plan_validated","acting","checkpointed","reflecting","waiting_for_help","waiting_for_approval","delegating","terminal"]),agentRunEpochV1Schema=e.object({schemaVersion:e.literal(AGENT_RUN_EPOCH_V1),id:o,runRef:o,epochNumber:e.number().int().positive(),planRef:o,budgetRef:o,startingCheckpointRef:o.optional(),startedAt:i,endedAt:i.optional(),activeComputeSeconds:e.number().int().nonnegative().max(900),modelCallCount:e.number().int().nonnegative(),toolCallCount:e.number().int().nonnegative(),effectAttemptCount:e.number().int().nonnegative(),evidence:e.array(r)}).strict().superRefine((t,n)=>{if(t.modelCallCount+t.toolCallCount>10)n.addIssue({code:e.ZodIssueCode.custom,path:["modelCallCount"],message:"An epoch must reflect after at most ten model/tool steps"});if(t.endedAt&&Date.parse(t.endedAt)<Date.parse(t.startedAt))n.addIssue({code:e.ZodIssueCode.custom,path:["endedAt"],message:"Epoch cannot end before it starts"});if(t.endedAt&&t.activeComputeSeconds*1000>Date.parse(t.endedAt)-Date.parse(t.startedAt))n.addIssue({code:e.ZodIssueCode.custom,path:["activeComputeSeconds"],message:"Active compute cannot exceed elapsed epoch time"})}),agentCheckpointV1Schema=e.object({schemaVersion:e.literal(AGENT_CHECKPOINT_V1),id:o,runRef:o,epochRef:o,sequence:e.number().int().positive(),phase:agentRunPhaseV1Schema,plan:s,stepRef:o.optional(),contextManifestRef:o,budgetSnapshotRef:o,durableStateRef:o,providerOutcome:e.enum(["none","definitive","indeterminate"]),reconciliationRef:o.optional(),evidence:e.array(r),createdAt:i,stateDigest:c}).strict().superRefine((t,n)=>{if(t.providerOutcome==="indeterminate"&&!t.reconciliationRef)n.addIssue({code:e.ZodIssueCode.custom,path:["reconciliationRef"],message:"Indeterminate provider outcomes require reconciliation"})}),agentProgressV1Schema=e.object({schemaVersion:e.literal(AGENT_PROGRESS_V1),id:o,runRef:o,sequence:e.number().int().positive(),phase:agentRunPhaseV1Schema,statusSummary:o,completedStepRefs:e.array(o),activeStepRefs:e.array(o),checkpointRef:o,durableStateRef:o,createdAt:i}).strict().superRefine((t,n)=>{const a=new Set(t.completedStepRefs);if(t.activeStepRefs.some((d)=>a.has(d)))n.addIssue({code:e.ZodIssueCode.custom,path:["activeStepRefs"],message:"A step cannot be both active and complete"});if(t.phase==="terminal"&&t.activeStepRefs.length>0)n.addIssue({code:e.ZodIssueCode.custom,path:["activeStepRefs"],message:"Terminal progress cannot retain active steps"})}),agentTerminalDecisionV1Schema=e.object({schemaVersion:e.literal(AGENT_TERMINAL_DECISION_V1),id:o,runRef:o,checkpointRef:o,plan:s,riskTier:l,decision:e.enum(["complete","blocked","cancelled","failed"]),statusSummary:o,completionCriteria:e.array(p),verification:m.optional(),blockingRef:o.optional(),decidedAt:i,decisionDigest:c}).strict().superRefine((t,n)=>{if(t.decision==="complete"){if(t.completionCriteria.length===0)n.addIssue({code:e.ZodIssueCode.custom,path:["completionCriteria"],message:"Completion requires explicit completion criteria"});if(t.completionCriteria.some((a)=>!a.satisfied||a.evidenceRefs.length===0))n.addIssue({code:e.ZodIssueCode.custom,path:["completionCriteria"],message:"Every completion criterion must have evidence"});if(!t.verification)n.addIssue({code:e.ZodIssueCode.custom,path:["verification"],message:"Completion requires execution-lane verification"})}else if(t.completionCriteria.length>0||t.verification)n.addIssue({code:e.ZodIssueCode.custom,path:["completionCriteria"],message:"Non-complete decisions cannot carry completion verification"});else if(!t.blockingRef&&t.decision==="blocked")n.addIssue({code:e.ZodIssueCode.custom,path:["blockingRef"],message:"Blocked decisions require a blocking reference"})}),agentEpochV1Schema=agentRunEpochV1Schema;export{validateAgentTerminalDecisionBindingV1}from"./reflection.js";

package/dist/node/agent/protocol/graph-validation.js

@@ -0,0 +1 @@
+import{validateAgentChildBudgetV1 as c}from"./budget.js";import{validateAgentExecutionVerificationV1 as p,validateAgentScopeExactV1 as d}from"./common.js";import{validateAgentTaskResultBindingV1 as u}from"./task-result-validation.js";export{validateAgentTaskResultBindingV1}from"./task-result-validation.js";function o(e,s){return e.ref===s.ref&&e.digest===s.digest}function f(e){return new Set(e).size!==e.length}function g(e,s){return JSON.stringify([...e].sort())===JSON.stringify([...s].sort())}export function validateAgentDelegationBindingV1(e){const{delegation:s,graph:i}=e,n=c({parent:e.parentBudget,child:s.budget}),a=i.tasks.find((t)=>t.id===s.taskRef);if(!o(s.taskGraph,{ref:i.id,digest:i.graphDigest}))n.push("Delegation task graph binding does not match");if(!a)return[...n,"Delegation task does not exist in its graph"];if(s.runRef!==i.runRef)n.push("Delegation run does not match its graph");if(e.parentBudget.id!==i.budgetRef||e.parentBudget.runRef!==i.runRef)n.push("Task graph parent budget does not match");if(i.tasks.length>e.parentBudget.maxTaskNodes)n.push("Task graph exceeds its parent task budget");if(i.participantRefs.length+1>e.parentBudget.maxParticipants)n.push("Task graph exceeds its parent participant budget");if(s.delegationDepth>e.parentBudget.maxDelegationDepth)n.push("Delegation depth exceeds its parent budget");if(s.parentPrincipalRef!==i.leadPrincipalRef)n.push("Delegation parent is not the task graph lead");if(!i.participantRefs.includes(s.derivedPrincipalRef))n.push("Delegation child is not a task graph participant");n.push(...d({expected:i.scope,observed:e.parentBudget.scope}),...d({expected:i.scope,observed:e.projection.targetScope}));if(!o(a.contextProjection,s.contextProjection)||!o(s.contextProjection,{ref:e.projection.id,digest:e.projection.projectionDigest}))n.push("Delegation context projection does not match its task");if(a.budget.ref!==s.budget.id||a.budget.digest!==s.budget.budgetDigest)n.push("Delegation child budget does not match its task");if(!o(s.parentBudget,{ref:e.parentBudget.id,digest:e.parentBudget.budgetDigest}))n.push("Delegation parent budget binding does not match");for(const t of s.toolRefs)if(!a.toolRefs.includes(t)||!e.parentToolRefs.includes(t))n.push(`Child tool is not derived: ${t}`);for(const t of s.grantBindings){if(!e.parentGrantRefs.includes(t.grantRef))n.push(`Child grant is not derived: ${t.grantRef}`);if(!a.grantRequirementRefs.includes(t.requirementRef))n.push(`Delegation has undeclared grant requirement: ${t.requirementRef}`)}for(const t of a.grantRequirementRefs)if(s.grantBindings.filter((r)=>r.requirementRef===t).length!==1)n.push(`Delegation does not satisfy grant requirement: ${t}`);if(!g(a.approvalRequirementRefs,s.approvalRequirementRefs))n.push("Delegation approval requirements do not match its task");return n}export function validateAgentTeamSynthesisBindingV1(e){const s=[];if(!o(e.synthesis.taskGraph,{ref:e.graph.id,digest:e.graph.graphDigest}))s.push("Team synthesis graph reference does not match");const i=new Map(e.results.map((t)=>[t.id,t]));if(f(e.synthesis.results.map((t)=>t.ref)))s.push("Team synthesis result references must be unique");for(const t of e.synthesis.results){const r=i.get(t.ref);if(!r||t.digest!==r.resultDigest)s.push(`Team synthesis has unknown or stale result: ${t.ref}`)}const n=e.synthesis.results.map((t)=>t.ref);if(!g(n,[...i.keys()]))s.push("Team synthesis result bindings do not match supplied results");const a=e.results.map((t)=>t.taskRef);if(f(a)||!g(a,e.graph.tasks.map((t)=>t.id)))s.push("Team synthesis result set does not cover the task graph");for(const t of e.results){const r=e.delegations.find((l)=>l.id===t.delegation.ref);if(!r)s.push(`Task result lacks its delegation: ${t.id}`);else s.push(...u({graph:e.graph,delegation:r,result:t}));if(e.synthesis.status!=="needs_resolution"&&t.status!=="ready_for_verification")s.push(`Team synthesis contains non-ready result: ${t.id}`)}if(e.synthesis.status==="verified")s.push(...p({expectedPolicyRef:e.graph.verificationPolicyRef,binding:e.synthesis.verification,canonical:e.canonicalVerification}));return s}

package/dist/node/agent/protocol/help.js

@@ -0,0 +1 @@
+import{z as e}from"zod";import{agentProtocolEvidencePointerSchema as i,agentProtocolRefSchema as t,agentProtocolTimestampSchema as o}from"./common.js";export const AGENT_UNCERTAINTY_V1="contractspec.agent.uncertainty.v1",AGENT_HELP_REQUEST_V1="contractspec.agent.help-request.v1",AGENT_HELP_RESPONSE_V1="contractspec.agent.help-response.v1",AGENT_ESCALATION_DECISION_V1="contractspec.agent.escalation-decision.v1",agentEscalationTriggerV1Schema=e.enum(["required_context_missing","required_context_stale","required_context_contradictory","identity_ambiguous","recipient_ambiguous","policy_conflict","risk_increased","confidence_below_threshold","capability_unavailable","connection_unavailable","grant_unavailable","model_unavailable","provider_unavailable","repeated_non_transient_failure","no_progress_replans","budget_eighty_percent_without_path","active_claim_conflict","prompt_injection_suspected","provenance_confusion_suspected","completion_unverifiable","sensitive_authority_unencoded"]),agentUncertaintyV1Schema=e.object({schemaVersion:e.literal(AGENT_UNCERTAINTY_V1),id:t,runRef:t,kind:e.enum(["missing_context","stale_context","contradictory_context","identity","recipient","policy_conflict","capability","provider_outcome","completion_claim","provenance","risk"]),summary:t,confidenceScore:e.number().min(0).max(1),evidenceRefs:e.array(t),blocksStepRefs:e.array(t),identifiedAt:o}).strict();const r=e.enum(["user","organization_operator","application_owner","human_specialist","qualified_specialist_agent","connection_doctor","authorization_administrator"]);export const agentHelpRequestV1Schema=e.object({schemaVersion:e.literal(AGENT_HELP_REQUEST_V1),id:t,runRef:t,checkpointRef:t,target:r,objectiveSummary:t,knownSummary:t,uncertaintyRefs:e.array(t).min(1),attemptRefs:e.array(t),evidence:e.array(i),unsafeContinuationSummary:t,minimalInputNeeded:t,safeOptionRefs:e.array(t).min(1),canContinueElsewhere:e.boolean(),createdAt:o,expiresAt:o.optional()}).strict().superRefine((n,a)=>{if(n.expiresAt&&Date.parse(n.expiresAt)<=Date.parse(n.createdAt))a.addIssue({code:e.ZodIssueCode.custom,path:["expiresAt"],message:"Help request expiry must follow creation"})}),agentHelpResponseV1Schema=e.object({schemaVersion:e.literal(AGENT_HELP_RESPONSE_V1),id:t,helpRequestRef:t,responderPrincipalRef:t,responseSummary:t,selectedOptionRef:t.optional(),evidence:e.array(i),responseAuthorityRef:t,createdAt:o}).strict(),agentEscalationDecisionV1Schema=e.object({schemaVersion:e.literal(AGENT_ESCALATION_DECISION_V1),id:t,runRef:t,decision:e.enum(["continue","request_help","terminate"]),triggers:e.array(agentEscalationTriggerV1Schema).min(1),triggerEvidenceRefs:e.array(t).min(1),helpRequestRef:t.optional(),reasonSummary:t,evidence:e.array(i),decidedAt:o}).strict().superRefine((n,a)=>{if(new Set(n.triggers).size!==n.triggers.length)a.addIssue({code:e.ZodIssueCode.custom,path:["triggers"],message:"Escalation triggers must be unique"});if(n.decision==="continue")a.addIssue({code:e.ZodIssueCode.custom,path:["decision"],message:"Mandatory protocol V1 escalation triggers cannot continue"});if(n.decision==="request_help"&&!n.helpRequestRef)a.addIssue({code:e.ZodIssueCode.custom,path:["helpRequestRef"],message:"Help escalation requires a help request reference"})});