create-windy 0.6.11 → 0.6.14

package/template/packages/server-sdk/src/debug-session-provider.ts

@@ -1,63 +1,14 @@
-import type { ModuleActor } from "./actor.js";
-
-export const MODULE_DEBUG_SESSION_SCHEMA_VERSION = 1 as const;
-
-export interface ModuleDebugSessionContextV1 {
-  readonly actor: ModuleActor;
-  readonly operationKey: string;
-  readonly signal: AbortSignal;
-}
-
-export interface ModuleDebugSessionListInputV1 extends ModuleDebugSessionContextV1 {
-  readonly limit: number;
-  /** Provider 私有的不透明 keyset cursor；Host 只原样回传给同一 Provider。 */
-  readonly cursor?: string;
-}
-
-export interface ModuleDebugSessionGetInputV1 extends ModuleDebugSessionContextV1 {
-  readonly sourceId: string;
-}
-
-export interface ModuleDebugSessionSummaryV1 {
-  /** 仅在 Provider 与 Host 之间使用，不会返回给 ADK Web。 */
-  readonly sourceId: string;
-  readonly title: string;
-  readonly scopeLabel?: string;
-  readonly updatedAt: string;
-  readonly revision: string;
-}
-
-export interface ModuleDebugSessionPageV1 {
-  readonly sessions: readonly ModuleDebugSessionSummaryV1[];
-  readonly truncated: boolean;
-  /** truncated=true 时必须提供，用于 Host 继续读取直到完整。 */
-  readonly next?: string;
-}
-
-export interface ModuleDebugSessionMessageV1 {
-  readonly sequence: number;
-  readonly role: "user" | "assistant";
-  readonly content: string;
-  readonly createdAt: string;
-}
-
-export interface ModuleDebugSessionV1 extends ModuleDebugSessionSummaryV1 {
-  readonly messages: readonly ModuleDebugSessionMessageV1[];
-}
-
-/**
- * 开发期 ADK Web 会话投影。Provider 只读业务事实，Host 负责重新授权、审计、
- * 有界校验与不透明 ID；V1 不支持业务会话的追加、重命名或删除。
- */
-export interface ModuleDebugSessionProviderV1 {
-  readonly schemaVersion: typeof MODULE_DEBUG_SESSION_SCHEMA_VERSION;
-  readonly key: string;
-  readonly operationKeys: readonly string[];
-  readonly featureKey: string;
-  readonly permissionKey: string;
-  readonly auditAction: string;
-  list(input: ModuleDebugSessionListInputV1): Promise<ModuleDebugSessionPageV1>;
-  get(
-    input: ModuleDebugSessionGetInputV1,
-  ): Promise<ModuleDebugSessionV1 | undefined>;
-}
+/** @deprecated 请改用 MODULE_AGENT_SESSION_SCHEMA_VERSION。 */
+export { MODULE_AGENT_SESSION_SCHEMA_VERSION as MODULE_DEBUG_SESSION_SCHEMA_VERSION } from "./agent-session-provider.js";
+
+/** @deprecated 请改用 ModuleAgentSession* 类型。 */
+export type {
+  ModuleAgentSessionContextV1 as ModuleDebugSessionContextV1,
+  ModuleAgentSessionGetInputV1 as ModuleDebugSessionGetInputV1,
+  ModuleAgentSessionListInputV1 as ModuleDebugSessionListInputV1,
+  ModuleAgentSessionMessageV1 as ModuleDebugSessionMessageV1,
+  ModuleAgentSessionPageV1 as ModuleDebugSessionPageV1,
+  ModuleAgentSessionProviderV1 as ModuleDebugSessionProviderV1,
+  ModuleAgentSessionSummaryV1 as ModuleDebugSessionSummaryV1,
+  ModuleAgentSessionV1 as ModuleDebugSessionV1,
+} from "./agent-session-provider.js";

package/template/packages/server-sdk/src/module-host.ts

@@ -1,5 +1,5 @@
 import type { ModuleAiOperationHandlerRegistration } from "./ai-operation-registration.js";
-import type { ModuleDebugSessionProviderV1 } from "./debug-session-provider.js";
+import type { ModuleAgentSessionProviderV1 } from "./agent-session-provider.js";
 import type { ModuleDurableHandlerDefinition } from "./durable-handler.js";
 import type { ModuleGovernedResourceRegistration } from "./data-governance-registration.js";
 import type { ModuleRolePreset } from "./role-preset.js";
@@ -69,9 +69,13 @@ export interface ModuleHost {
   registerRolePresets(presets: readonly ModuleRolePreset[]): void;
   /** 注册 Manifest `providers` 已声明的搜索 Provider。 */
   registerSearchProviders(providers: readonly ModuleSearchProvider[]): void;
-  /** 注册开发期 ADK Web 使用的只读业务会话投影。 */
+  /** 注册主站使用的只读业务会话投影。 */
+  registerAgentSessionProviders(
+    providers: readonly ModuleAgentSessionProviderV1[],
+  ): void;
+  /** @deprecated 请改用 registerAgentSessionProviders。 */
   registerDebugSessionProviders(
-    providers: readonly ModuleDebugSessionProviderV1[],
+    providers: readonly ModuleAgentSessionProviderV1[],
   ): void;
 }
 

package/template/packages/server-sdk/src/request-context.ts

@@ -4,6 +4,8 @@ import type { ModuleAiArtifactPort } from "./ai-artifact-port.js";
 import type { ModuleAiOperationPort } from "./ai-operation-port.js";
 import type { ModuleAiOperationReadinessPortV1 } from "./ai-runtime-readiness.js";
 import type { ModuleAiScreenshotIntakePortV1 } from "./ai-screenshot-intake-port.js";
+import type { ModuleAgentSessionMemoryPortV1 } from "./agent-session-memory-port.js";
+import type { ModuleAuthoritativeSourceInvalidationPortV1 } from "./agent-source-invalidation-port.js";
 import type { ModuleJobPort } from "./jobs-port.js";
 import type { ModuleReportStagingPortV1 } from "./report-staging-port.js";
 import type { ModuleSecretPort } from "./secret-port.js";
@@ -37,6 +39,10 @@ export interface ModuleRequestContext {
   readonly aiReadiness?: ModuleAiOperationReadinessPortV1;
   /** VLM 截图输入的独立版本化接缝，不改变既有 aiArtifacts 必填表面。 */
   readonly screenshots?: ModuleAiScreenshotIntakePortV1;
+  /** Module-authoritative long-session Memory triggers; absent means fail closed. */
+  readonly sessionMemory?: ModuleAgentSessionMemoryPortV1;
+  /** Host-bound authoritative source lifecycle and authorization revocation outbox. */
+  readonly sourceInvalidation?: ModuleAuthoritativeSourceInvalidationPortV1;
   readonly jobs: ModuleJobPort;
   /** 大报告受治理暂存是版本化、可选的 additive seam。 */
   readonly reportStaging?: ModuleReportStagingPortV1;

package/template/packages/shared/index.ts

@@ -2,6 +2,9 @@ export * from "./src/audit.js";
 export * from "./src/ai-operation-readiness.js";
 // @windy-module system.agent begin
 export * from "./src/ai-runtime-report.js";
+export * from "./src/agent-workflow.js";
+export * from "./src/agent-workflow-events.js";
+export * from "./src/agent-workflow-evaluation.js";
 // @windy-module system.agent end
 export * from "./src/database.js";
 export * from "./src/data-governance.js";

package/template/packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/shared",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/shared/src/agent-workflow-definition.ts

@@ -0,0 +1,113 @@
+import type { ISODateTime } from "./primitives.js";
+import type { AgentWorkflowBudget } from "./agent-workflow-run.js";
+
+export const AGENT_WORKFLOW_SCHEMA_VERSION = 1 as const;
+
+export type AgentWorkflowNodeType =
+  | "model"
+  | "tool"
+  | "subagent"
+  | "condition"
+  | "parallel"
+  | "join"
+  | "approval"
+  | "job"
+  | "wait"
+  | "artifact"
+  | "final";
+
+export type AgentWorkflowFailurePolicy =
+  | { readonly mode: "fail-run" }
+  | {
+      readonly mode: "retry";
+      readonly maxAttempts: number;
+      readonly backoffSeconds: number;
+      readonly exhausted: "fail-run" | "skip";
+    }
+  | { readonly mode: "fallback"; readonly nodeId: string }
+  | { readonly mode: "skip" };
+
+interface NodeBase<T extends AgentWorkflowNodeType> {
+  readonly id: string;
+  readonly type: T;
+  readonly label: string;
+  readonly inputSchemaKey?: string;
+  readonly outputSchemaKey?: string;
+  readonly timeoutSeconds?: number;
+  readonly failurePolicy: AgentWorkflowFailurePolicy;
+}
+
+export type AgentWorkflowNode =
+  | (NodeBase<"model"> & {
+      readonly operationKey: string;
+      readonly promptKey: string;
+    })
+  | (NodeBase<"tool"> & {
+      readonly toolKey: string;
+      readonly effect: "read" | "write";
+    })
+  | (NodeBase<"subagent"> & {
+      readonly capabilityKey: string;
+      readonly operationKey: string;
+      readonly allowedToolKeys: readonly string[];
+      readonly requiredFeatureKeys: readonly string[];
+      readonly requiredPermissionKeys: readonly string[];
+      readonly allowedLicenseVersions?: readonly string[];
+      readonly workspacePolicyKey: string;
+      readonly scopePolicyKey: string;
+      readonly budget: AgentWorkflowBudget;
+    })
+  | (NodeBase<"condition"> & {
+      readonly conditionKey: string;
+      readonly branches: readonly string[];
+    })
+  | (NodeBase<"parallel"> & { readonly maxConcurrency: number })
+  | (NodeBase<"join"> & { readonly strategy: "all" | "all-settled" | "any" })
+  | (NodeBase<"approval"> & {
+      readonly title: string;
+      readonly candidateRoles: readonly string[];
+    })
+  | (NodeBase<"job"> & { readonly taskKey: string })
+  | (NodeBase<"wait"> & { readonly signalKey: string })
+  | (NodeBase<"artifact"> & {
+      readonly policyKey: string;
+      readonly artifactKind: string;
+    })
+  | (NodeBase<"final"> & { readonly outputSchemaKey: string });
+
+export interface AgentWorkflowEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly branch?: string;
+}
+
+export interface AgentWorkflowDefinition {
+  readonly schemaVersion: typeof AGENT_WORKFLOW_SCHEMA_VERSION;
+  readonly workflowKey: string;
+  readonly version: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly entryNodeId: string;
+  readonly nodes: readonly AgentWorkflowNode[];
+  readonly edges: readonly AgentWorkflowEdge[];
+  readonly budget: AgentWorkflowBudget;
+}
+
+export interface AgentWorkflowReleaseCoordinates {
+  readonly runtimeVersion: string;
+  readonly routeVersion: string;
+  readonly promptVersion: string;
+  readonly toolSchemaVersion: string;
+  readonly manifestDigest: string;
+}
+
+export interface AgentWorkflowRelease {
+  readonly releaseId: string;
+  readonly releaseDigest: string;
+  readonly definitionId: string;
+  readonly definitionDigest: string;
+  readonly definition: AgentWorkflowDefinition;
+  readonly coordinates: AgentWorkflowReleaseCoordinates;
+  readonly publishedBy: string;
+  readonly publishedAt: ISODateTime;
+}

package/template/packages/shared/src/agent-workflow-delegation.ts

@@ -0,0 +1,123 @@
+import type { JsonValue } from "./json.js";
+import type { ISODateTime } from "./primitives.js";
+import type {
+  AgentWorkflowArtifactRef,
+  AgentWorkflowBudget,
+  AgentWorkflowUsage,
+} from "./agent-workflow-run.js";
+
+export interface AgentDelegationGrant {
+  readonly delegationId: string;
+  readonly parentRunId: string;
+  readonly parentNodeId: string;
+  readonly parentNodeRunId: string;
+  readonly childSessionId: string;
+  readonly childAgentRunId?: string;
+  readonly capabilityCeiling: {
+    readonly capabilityKey: string;
+    readonly allowedToolKeys: readonly string[];
+    readonly requiredFeatureKeys: readonly string[];
+    readonly requiredPermissionKeys: readonly string[];
+    readonly allowedLicenseVersions?: readonly string[];
+    readonly workspacePolicyKey: string;
+    readonly workspaceId: string;
+    readonly scopeSnapshot: import("./rbac.js").AuthorizationScopeSnapshot;
+    readonly scopePolicyDigest: string;
+    readonly policyDigest: string;
+    readonly authorizationProofId: string;
+    readonly runPolicyDigest: string;
+    readonly scopeDigest: string;
+    readonly authorizationSnapshotDigest: string;
+  };
+  readonly budget: AgentWorkflowBudget;
+  readonly status: "created" | "running" | "completed" | "failed" | "cancelled";
+  readonly outputArtifacts: readonly AgentWorkflowArtifactRef[];
+}
+
+export interface AgentWorkflowBudgetReservation {
+  readonly reservationId: string;
+  readonly parentRunId: string;
+  readonly parentNodeRunId: string;
+  readonly delegationId: string;
+  readonly idempotencyKey: string;
+  readonly authorizationProofId: string;
+  readonly authorizationSnapshotDigest: string;
+  readonly runPolicyDigest: string;
+  readonly reserved: AgentWorkflowBudget;
+  readonly consumed: AgentWorkflowUsage;
+  readonly status: "active" | "settled" | "released";
+  readonly usageReceiptId?: string;
+  readonly reasonCode?: string;
+  readonly settledAt?: ISODateTime;
+  readonly version: number;
+  readonly createdAt: ISODateTime;
+  readonly updatedAt: ISODateTime;
+}
+
+export interface AgentWorkflowSideEffectCommand {
+  readonly commandId: string;
+  readonly runId: string;
+  readonly nodeRunId: string;
+  readonly effectKind: "tool" | "approval" | "job" | "subagent";
+  readonly effectKey: string;
+  readonly adapter: {
+    readonly kind:
+      | "agent-tool"
+      | "approval-work-item"
+      | "durable-job"
+      | "child-agent";
+    readonly coordinate: string;
+  };
+  readonly idempotencyKey: string;
+  readonly requestDigest: string;
+  readonly generation: number;
+  readonly fenceTokenDigest?: string;
+  readonly authorizationSnapshotDigest?: string;
+  readonly runPolicyDigest?: string;
+  readonly budgetReservationId?: string;
+  readonly delegationId?: string;
+  readonly status:
+    | "prepared"
+    | "dispatched"
+    | "cancellation-requested"
+    | "committed"
+    | "reconciled"
+    | "cancelled"
+    | "failed";
+  readonly safeErrorCode?: string;
+  readonly claimedAt?: ISODateTime;
+  readonly committedAt?: ISODateTime;
+  readonly version: number;
+  readonly createdAt: ISODateTime;
+  readonly updatedAt: ISODateTime;
+}
+
+export interface AgentWorkflowSideEffectReceipt {
+  readonly receiptId: string;
+  readonly commandId: string;
+  readonly runId: string;
+  readonly nodeRunId: string;
+  readonly effectKind: AgentWorkflowSideEffectCommand["effectKind"];
+  readonly generation: number;
+  readonly fenceTokenDigest: string;
+  readonly requestDigest: string;
+  readonly externalReceiptId: string;
+  readonly resultDigest: string;
+  readonly smallResult?: JsonValue;
+  readonly artifactRefs?: readonly AgentWorkflowArtifactRef[];
+  readonly authorizationSnapshotDigest: string;
+  readonly runPolicyDigest: string;
+  readonly committedAt: ISODateTime;
+}
+
+export function budgetFitsWithin(
+  child: AgentWorkflowBudget,
+  parent: AgentWorkflowBudget,
+): boolean {
+  return (Object.keys(parent) as Array<keyof AgentWorkflowBudget>).every(
+    (key) =>
+      Number.isSafeInteger(child[key]) &&
+      child[key] >= 0 &&
+      child[key] <= parent[key],
+  );
+}

package/template/packages/shared/src/agent-workflow-evaluation.ts

@@ -0,0 +1,159 @@
+import type { ISODateTime } from "./primitives.js";
+import type {
+  AgentWorkflowArtifactRef,
+  AgentWorkflowBudget,
+  AgentWorkflowMeasuredCost,
+  AgentWorkflowMeasuredCount,
+} from "./agent-workflow-run.js";
+
+export type AgentWorkflowEvaluationArmKind = "single-agent" | "multi-agent";
+
+export interface AgentWorkflowEvaluationReleaseIdentity {
+  readonly releaseDigest: string;
+  readonly routeVersion: string;
+  readonly promptVersion: string;
+  readonly manifestDigest: string;
+}
+
+export interface AgentWorkflowEvaluationConditions {
+  readonly inputDigest: string | null;
+  readonly modelRouteKey: string | null;
+  readonly model: string | null;
+  readonly modelDeploymentDigest: string | null;
+  readonly modelConfigurationDigest: string | null;
+  readonly toolSchemaDigest: string;
+  readonly toolRuntimePolicyDigest: string | null;
+  readonly allowedToolKeys: readonly string[];
+  readonly budget: AgentWorkflowBudget;
+  readonly scopeDigest: string;
+  readonly authorizationSnapshotDigest: string | null;
+  readonly workspacePolicyDigest: string | null;
+  readonly executionPolicyDigest: string | null;
+  readonly runtimeVersion: string;
+}
+
+export type AgentWorkflowEvaluationAvailability =
+  | { readonly status: "run"; readonly runId: string }
+  | { readonly status: "unavailable"; readonly reasonCode: string };
+
+export interface AgentWorkflowEvaluationArmCoordinates {
+  readonly releaseId: string;
+  readonly release: AgentWorkflowEvaluationReleaseIdentity;
+  readonly conditions: AgentWorkflowEvaluationConditions;
+  readonly availability: AgentWorkflowEvaluationAvailability;
+}
+
+export interface AgentWorkflowEvaluationIdentity {
+  readonly evaluationSetKey: string;
+  readonly evaluationSetVersion: string;
+  readonly caseKey: string;
+  readonly caseVersion: string;
+  readonly trialKey: string;
+  readonly trialIndex: number;
+  readonly scopeDigest: string;
+  readonly singleAgent: AgentWorkflowEvaluationArmCoordinates;
+  readonly multiAgent: AgentWorkflowEvaluationArmCoordinates;
+  readonly rubricKey: string;
+  readonly rubricVersion: string;
+}
+
+export interface AgentWorkflowEvaluationMismatchEvidence {
+  readonly source: "requested-vs-observed" | "arm-comparison";
+  readonly field: string;
+  readonly reasonCode: string;
+  readonly expectedDigest: string;
+  readonly observedDigest?: string;
+  readonly counterpartArm?: AgentWorkflowEvaluationArmKind;
+}
+
+export interface AgentWorkflowEvaluationFailure {
+  readonly category:
+    | "model"
+    | "tool"
+    | "authorization"
+    | "approval"
+    | "job"
+    | "recovery"
+    | "budget"
+    | "runtime";
+  readonly stage: string;
+  readonly safeCode: string;
+}
+
+export interface AgentWorkflowHumanHandoff {
+  readonly reason: string;
+  readonly outcome: "resolved" | "unresolved" | "cancelled";
+  readonly durationMs: number;
+}
+
+export interface AgentWorkflowEvaluationMetrics {
+  readonly outcome:
+    | "completed"
+    | "failed"
+    | "cancelled"
+    | "timed-out"
+    | "invalid";
+  readonly latencyMs: number;
+  readonly cost: AgentWorkflowMeasuredCost;
+  readonly inputTokens: AgentWorkflowMeasuredCount;
+  readonly outputTokens: AgentWorkflowMeasuredCount;
+  readonly failures: readonly AgentWorkflowEvaluationFailure[];
+  readonly humanHandoffs: readonly AgentWorkflowHumanHandoff[];
+  readonly evidenceQuality:
+    | {
+        readonly status: "graded";
+        readonly score: number;
+        readonly source: "rubric-evidence";
+      }
+    | { readonly status: "unknown"; readonly reasonCode: string };
+  readonly safety:
+    | {
+        readonly status: "measured";
+        readonly refusalCount: number;
+        readonly unsafeAllowCount: number;
+        readonly source: "host-audit";
+      }
+    | { readonly status: "unknown"; readonly reasonCode: string };
+  readonly recovery:
+    | {
+        readonly status: "measured";
+        readonly attemptCount: number;
+        readonly succeeded: boolean;
+        readonly source: "workflow-run";
+      }
+    | { readonly status: "unknown"; readonly reasonCode: string };
+}
+
+export interface AgentWorkflowEvaluationArm {
+  readonly kind: AgentWorkflowEvaluationArmKind;
+  readonly status: "pending" | "completed" | "unavailable" | "invalid";
+  readonly coordinates: AgentWorkflowEvaluationArmCoordinates;
+  readonly runId?: string;
+  readonly metrics?: AgentWorkflowEvaluationMetrics;
+  readonly evidenceArtifacts: readonly AgentWorkflowArtifactRef[];
+  readonly mismatchEvidence: readonly AgentWorkflowEvaluationMismatchEvidence[];
+  readonly dispositionReason?: string;
+}
+
+export interface AgentWorkflowEvaluationRecord {
+  readonly evaluationId: string;
+  readonly tenantId: string;
+  readonly createdBy: string;
+  readonly identity: AgentWorkflowEvaluationIdentity;
+  readonly identityDigest: string;
+  readonly singleAgent: AgentWorkflowEvaluationArm;
+  readonly multiAgent: AgentWorkflowEvaluationArm;
+  readonly status: "pending" | "completed" | "unavailable" | "non-comparable";
+  readonly dispositionReason?: string;
+  readonly createdAt: ISODateTime;
+  readonly completedAt?: ISODateTime;
+}
+
+export interface AgentWorkflowEvaluationSummary {
+  readonly evaluationSetKey: string;
+  readonly evaluationSetVersion: string;
+  readonly comparableSampleCount: number;
+  readonly totalSampleCount: number;
+  readonly singleAgentCompletionRate?: number;
+  readonly multiAgentCompletionRate?: number;
+}

package/template/packages/shared/src/agent-workflow-events.ts

@@ -0,0 +1,99 @@
+import type { ISODateTime } from "./primitives.js";
+import type {
+  AgentWorkflowArtifactRef,
+  AgentWorkflowInputReceipt,
+} from "./agent-workflow.js";
+
+export const AGENT_WORKFLOW_EVENT_SCHEMA_VERSION = 1 as const;
+
+export type AgentWorkflowEventData =
+  | {
+      readonly type: "workflow.run-created";
+      readonly releaseId: string;
+      readonly inputReceipt: AgentWorkflowInputReceipt;
+      readonly parentRunId?: string;
+      readonly parentNodeId?: string;
+      readonly parentNodeRunId?: string;
+      readonly delegationId?: string;
+    }
+  | { readonly type: "workflow.run-started" }
+  | {
+      readonly type: "workflow.wait-signalled";
+      readonly nodeRunId: string;
+      readonly signalKey: string;
+      readonly payloadDigest: string;
+      readonly receiptId: string;
+    }
+  | {
+      readonly type:
+        | "workflow.run-completed"
+        | "workflow.run-failed"
+        | "workflow.run-cancelled"
+        | "workflow.run-timed-out";
+      readonly safeCode?: string;
+    }
+  | {
+      readonly type: "workflow.cancellation-requested";
+      readonly reasonCode: string;
+    }
+  | {
+      readonly type:
+        | "workflow.recovery-started"
+        | "workflow.recovery-completed";
+      readonly recoveryNumber: number;
+    }
+  | {
+      readonly type: "workflow.recovery-waiting" | "workflow.recovery-failed";
+      readonly recoveryNumber: number;
+      readonly safeCode: string;
+      readonly unresolvedCount: number;
+    }
+  | {
+      readonly type:
+        | "workflow.node-ready"
+        | "workflow.node-started"
+        | "workflow.node-waiting"
+        | "workflow.node-completed"
+        | "workflow.node-failed"
+        | "workflow.node-cancelled"
+        | "workflow.node-skipped"
+        | "workflow.node-timed-out"
+        | "workflow.node-retry-scheduled";
+      readonly nodeRunId: string;
+      readonly nodeId: string;
+      readonly resultDigest?: string;
+      readonly receiptId?: string;
+      readonly safeCode?: string;
+    }
+  | {
+      readonly type:
+        | "workflow.delegation-created"
+        | "workflow.delegation-child-linked"
+        | "workflow.delegation-completed"
+        | "workflow.delegation-failed"
+        | "workflow.delegation-cancel-requested";
+      readonly delegationId: string;
+      readonly parentNodeId: string;
+      readonly parentNodeRunId: string;
+      readonly childSessionId: string;
+      readonly childAgentRunId?: string;
+      readonly artifactIds?: readonly string[];
+      readonly safeCode?: string;
+    }
+  | {
+      readonly type: "workflow.artifact-linked";
+      readonly nodeRunId: string;
+      readonly artifact: AgentWorkflowArtifactRef;
+    };
+
+export interface AgentWorkflowEventEnvelope {
+  readonly schemaVersion: typeof AGENT_WORKFLOW_EVENT_SCHEMA_VERSION;
+  readonly eventId: string;
+  readonly workflowRunId: string;
+  readonly sequence: number;
+  readonly occurredAt: ISODateTime;
+  readonly causationEventId?: string;
+  readonly parentEventId?: string;
+  readonly childWorkflowRunId?: string;
+  readonly data: AgentWorkflowEventData;
+}