ai-workflow-contract 0.1.8 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-contract",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "private": false,
   "description": "Shared AI workflow contracts over WorkCtrlFlow and EagerDataFlow substrates",
   "type": "module",
@@ -9,8 +9,8 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "eager-data-flow-contract": "0.1.3",
-    "halfcode-compiler.xnl": "0.2.2",
+    "eager-data-flow-contract": "0.1.4",
+    "halfcode-compiler.xnl": "0.2.9",
     "task-manager-contract": "0.1.3",
     "work-ctrl-flow-contract": "0.1.3"
   },

package/src/index.ts

@@ -8,6 +8,9 @@ import type {
   ResourceValue,
   Sha256Digest,
 } from 'halfcode-compiler.xnl/resource-core';
+import type {
+  ResourceAuthoringProposal,
+} from 'halfcode-compiler.xnl/authoring-runtime';
 import type {
   FlowBundleSpec,
   FlowClosedObject,
@@ -156,6 +159,8 @@ export type MaterialCardinality = 'one' | 'many';
 export type AIWorkflowAgentResourceRelation =
   | 'agent-message-prompt'
   | 'agent-message-schema'
+  | 'agent-message-source'
+  | 'agent-context-pipeline'
   | 'agent-input-schema'
   | 'agent-output-schema'
   | 'agent-tool'
@@ -196,6 +201,20 @@ export interface AIAgentMessageProjection {
   readonly schema?: AIWorkflowMessageSchemaProjection;
 }
 
+export interface AIAgentStaticMessagePrefixProjection extends AIAgentMessageProjection {
+  readonly type: 'message';
+}
+
+export interface AIAgentMessageSourcePrefixProjection {
+  readonly type: 'message-source';
+  readonly id: string;
+  readonly source: AIWorkflowTypedResourceRef;
+}
+
+export type AIAgentMessagePrefixItemProjection =
+  | AIAgentStaticMessagePrefixProjection
+  | AIAgentMessageSourcePrefixProjection;
+
 export interface MaterialPortProjection {
   readonly kind: 'MaterialPort';
   readonly fqn: string;
@@ -210,7 +229,10 @@ export interface AIAgentDefinitionProjection {
   readonly kind: 'AIAgentDefinition';
   readonly fqn: string;
   readonly resource: ResourceRecord;
+  readonly messagePrefix: readonly AIAgentMessagePrefixItemProjection[];
+  /** Static compatibility view for legacy consumers during MessagePrefix adoption. */
   readonly messages: readonly AIAgentMessageProjection[];
+  readonly contextPipeline?: AIWorkflowTypedResourceRef;
   readonly inputSchema?: AIWorkflowMessageSchemaProjection;
   readonly outputSchema?: AIWorkflowMessageSchemaProjection;
   readonly tools: readonly AIWorkflowTypedResourceRef[];
@@ -258,6 +280,131 @@ export interface FrozenAIAgentTaskBinding {
   readonly closureResourceIds: readonly string[];
 }
 
+export const AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION =
+  'ai-workflow.agent-definition-selection/v1' as const;
+
+export interface AIAgentTaskRequirement {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly requirementId: string;
+  /** Audit/model evidence only. It is never a code-level routing input. */
+  readonly objective: string;
+  readonly inputSchemaRef?: `resource://${string}`;
+  readonly outputSchemaRef?: `resource://${string}`;
+  readonly requiredToolRefs: readonly `resource://${string}`[];
+  readonly requiredEffectPolicyRef?: `resource://${string}`;
+  readonly requiredToolMode?: AIWorkflowEffectToolMode;
+  readonly requiredMaterialPortRefs: readonly `resource://${string}`[];
+  readonly requiredContextPipelineRef?: `resource://${string}`;
+  readonly requiredMessageSourceRefs: readonly `resource://${string}`[];
+}
+
+export interface AIAgentTaskRequirementProjection {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly requirement: AIAgentTaskRequirement;
+  readonly requirementDigest: Sha256Digest;
+}
+
+export interface AIAgentDefinitionCandidateContract {
+  readonly inputSchemaRef?: `resource://${string}`;
+  readonly outputSchemaRef?: `resource://${string}`;
+  readonly toolRefs: readonly `resource://${string}`[];
+  readonly effectPolicyRef?: `resource://${string}`;
+  readonly effectToolMode?: AIWorkflowEffectToolMode;
+  readonly materialPortRefs: readonly `resource://${string}`[];
+  readonly contextPipelineRef?: `resource://${string}`;
+  readonly messageSourceRefs: readonly `resource://${string}`[];
+}
+
+export interface AIAgentDefinitionAuthoringEvidence {
+  readonly schemaVersion: 'ai-workflow.agent-definition-authoring-evidence/v1';
+  readonly planDigest: Sha256Digest;
+  readonly transactionId: string;
+  readonly receiptDigest: Sha256Digest;
+}
+
+export interface AIAgentDefinitionCandidate {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly agentDefinitionRef: `resource://${string}`;
+  readonly contentDigest: Sha256Digest;
+  readonly registryRevision: Sha256Digest;
+  readonly contract: AIAgentDefinitionCandidateContract;
+  readonly candidateDigest: Sha256Digest;
+  readonly authoringEvidence?: AIAgentDefinitionAuthoringEvidence;
+}
+
+export interface AIAgentDefinitionCandidateSet {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly registryRevision: Sha256Digest;
+  readonly candidates: readonly AIAgentDefinitionCandidate[];
+  readonly candidateSetDigest: Sha256Digest;
+}
+
+interface AIAgentDefinitionSelectionDecisionBase {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly requirementDigest: Sha256Digest;
+  readonly candidateSetDigest: Sha256Digest;
+  readonly reason: string;
+}
+
+export interface SelectExistingAIAgentDefinitionDecision
+  extends AIAgentDefinitionSelectionDecisionBase {
+  readonly mode: 'select-existing';
+  readonly candidateRef: `resource://${string}`;
+  readonly candidateDigest: Sha256Digest;
+}
+
+export interface AuthorNewAIAgentDefinitionDecision
+  extends AIAgentDefinitionSelectionDecisionBase {
+  readonly mode: 'author-new';
+  readonly agentDefinitionRef: `resource://${string}`;
+  readonly proposal: ResourceAuthoringProposal;
+}
+
+export type AIAgentDefinitionSelectionDecision =
+  | SelectExistingAIAgentDefinitionDecision
+  | AuthorNewAIAgentDefinitionDecision;
+
+export type AIAgentDefinitionSelectionRejectionCode =
+  | 'decision-invalid'
+  | 'requirement-stale'
+  | 'candidate-set-stale'
+  | 'candidate-missing'
+  | 'candidate-digest-mismatch'
+  | 'candidate-incompatible'
+  | 'authoring-in-progress'
+  | 'authoring-proposal-invalid';
+
+export interface SelectedAIAgentDefinitionAdmission {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly status: 'selected';
+  readonly requirementDigest: Sha256Digest;
+  readonly candidateSetDigest: Sha256Digest;
+  readonly candidate: AIAgentDefinitionCandidate;
+  readonly reason: string;
+}
+
+export interface AuthorNewAIAgentDefinitionAdmission {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly status: 'authoring-request';
+  readonly requirementDigest: Sha256Digest;
+  readonly candidateSetDigest: Sha256Digest;
+  readonly agentDefinitionRef: `resource://${string}`;
+  readonly proposal: ResourceAuthoringProposal;
+  readonly reason: string;
+}
+
+export interface RejectedAIAgentDefinitionAdmission {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly status: 'rejected';
+  readonly code: AIAgentDefinitionSelectionRejectionCode;
+  readonly message: string;
+}
+
+export type AIAgentDefinitionSelectionAdmission =
+  | SelectedAIAgentDefinitionAdmission
+  | AuthorNewAIAgentDefinitionAdmission
+  | RejectedAIAgentDefinitionAdmission;
+
 export type AIWorkflowNodeType =
   | 'agent'
   | 'data'
@@ -410,8 +557,8 @@ export interface AIWorkflowExecutionReceipt {
 }
 
 export type AIAgentSelector =
-  | { readonly byInstanceId: string; readonly byInstanceName?: never }
-  | { readonly byInstanceName: string; readonly byInstanceId?: never };
+  | { readonly byId: string; readonly byName?: never }
+  | { readonly byName: string; readonly byId?: never };
 
 export interface AIAgentInvocation<Input extends FlowClosedValue = FlowClosedValue> {
   readonly kind: 'ai.agent';