@tangle-network/agent-interface 1.2.0 → 1.4.0

package/dist/environment-runtime.js

@@ -113,6 +113,10 @@ export function agentNativeContextContinuationResultMatchesRequest(request, outc
         (exactOutcome.result.sessionId === undefined ||
             exactOutcome.result.sessionId === current.sessionId));
 }
+export const AgentEnvironmentCreationSchema = z.enum([
+    "created",
+    "replayed",
+]);
 /** Strict runtime validator for provider capability negotiation. */
 export const AgentEnvironmentCapabilitiesSchema = z
     .strictObject({
@@ -325,12 +329,34 @@ export function agentEnvironmentCreateInputDigest(input) {
         input: material,
     });
 }
+/**
+ * Return the per-call view of an environment that a same-key create replayed.
+ *
+ * The view shares every member of the environment, so operations act on the
+ * one environment, and it states `creation: "replayed"` because this call
+ * provisioned nothing. The copy is shallow, so the environment must be a plain
+ * object whose members do not read `this`; a class instance loses its
+ * prototype members in a copy and is rejected.
+ * @internal
+ */
+export function replayedAgentEnvironmentView(environment) {
+    const prototype = Object.getPrototypeOf(environment);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new Error("a replayed agent environment view requires a plain object environment");
+    }
+    return { ...environment, creation: "replayed" };
+}
 /**
  * Apply the generic create contract to one provider adapter's keyed requests.
  *
  * The provider's backing service remains responsible for retaining the key
  * across adapter reconstruction. This helper coalesces concurrent retries and
  * rejects collisions before the provider performs another create effect.
+ *
+ * The call that runs `create` receives the environment the provider built,
+ * with the creation verdict the provider could prove. Every same-key call
+ * after it, including one that awaited the same pending create, receives
+ * {@link replayedAgentEnvironmentView} of that environment.
  * @internal
  */
 export async function createAgentEnvironmentWithIdempotency(records, input, create) {
@@ -344,7 +370,7 @@ export async function createAgentEnvironmentWithIdempotency(records, input, crea
         if (existing.digest !== digest) {
             throw new Error("agent environment create idempotency key conflicts with a different create input");
         }
-        return existing.environment ?? existing.pending;
+        return replayedAgentEnvironmentView(existing.environment ?? (await existing.pending));
     }
     const pending = Promise.resolve().then(create);
     const record = {

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export * from "./host-services.js";
 export * from "./mcp.js";
 export * from "./provider-adapter.js";
 export type * from "./environment-provider.js";
-export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, createAgentEnvironmentWithIdempotency, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, AgentEnvironmentCreationSchema, createAgentEnvironmentWithIdempotency, replayedAgentEnvironmentView, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
 export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";

package/dist/index.js

@@ -7,7 +7,7 @@ export * from "./provider-config.js";
 export * from "./host-services.js";
 export * from "./mcp.js";
 export * from "./provider-adapter.js";
-export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, createAgentEnvironmentWithIdempotency, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, AgentEnvironmentCreationSchema, createAgentEnvironmentWithIdempotency, replayedAgentEnvironmentView, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
 export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";

package/dist/runtime-control.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { canonicalCandidateDigest, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 import { boundedIdentifierSchema, boundedJsonRecordSchema, boundedJsonSchema, boundedStringSchema, } from "./contract-limits.js";
+import { ModelUsageSchema } from "./environment-observation.js";
 import { InteractionRequestSchema } from "./interaction.js";
 import { DurablePlanSchema } from "./plan.js";
 const stableIdSchema = boundedIdentifierSchema;
@@ -263,6 +264,70 @@ const partSchema = z.discriminatedUnion("type", [
         agent: stableIdSchema,
     }),
 ]);
+const TERMINAL_CHILD_TASK_STATUSES = new Set(["completed", "failed", "cancelled"]);
+const epochMillisecondsSchema = z.number().finite().nonnegative();
+/**
+ * Provider-native child task lifecycle. Identity comes only from `childId`,
+ * `parentChildId`, and `sourceEventId`; `raw` is opaque and bounded. A provider
+ * without a stable `childId` emits no `child-task` event.
+ */
+const ChildTaskEventSchema = z
+    .strictObject({
+    type: z.literal("child-task"),
+    childId: stableIdSchema,
+    parentChildId: stableIdSchema.optional(),
+    status: z.enum(["started", "running", "completed", "failed", "cancelled"]),
+    title: boundedStringSchema.optional(),
+    time: z.strictObject({
+        started: epochMillisecondsSchema,
+        updated: epochMillisecondsSchema,
+        ended: epochMillisecondsSchema.optional(),
+    }),
+    runner: stableIdSchema.optional(),
+    model: stableIdSchema.optional(),
+    usage: ModelUsageSchema.optional(),
+    terminalReason: boundedStringSchema.optional(),
+    sourceEventId: stableIdSchema,
+    raw: boundedJsonRecordSchema.optional(),
+})
+    .superRefine((event, refinement) => {
+    const terminal = TERMINAL_CHILD_TASK_STATUSES.has(event.status);
+    if (!terminal && event.time.ended !== undefined) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["time", "ended"],
+            message: "only a terminal child task status may carry an end time",
+        });
+    }
+    if (!terminal && event.terminalReason !== undefined) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["terminalReason"],
+            message: "only a terminal child task status may carry a terminal reason",
+        });
+    }
+    if (event.time.updated < event.time.started) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["time", "updated"],
+            message: "a child task update time cannot precede its start time",
+        });
+    }
+    if (event.time.ended !== undefined && event.time.ended < event.time.started) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["time", "ended"],
+            message: "a child task end time cannot precede its start time",
+        });
+    }
+    if (event.parentChildId === event.childId) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["parentChildId"],
+            message: "a child task cannot be its own parent",
+        });
+    }
+});
 /** Runtime validator for every member of the existing canonical event union. */
 export const CanonicalStreamEventSchema = z.discriminatedUnion("type", [
     z.strictObject({
@@ -332,6 +397,7 @@ export const CanonicalStreamEventSchema = z.discriminatedUnion("type", [
         type: z.literal("plan.submitted"),
         plan: DurablePlanSchema,
     }),
+    ChildTaskEventSchema,
 ]);
 export const RuntimeEventEnvelopeSchema = z.strictObject({
     runId: stableIdSchema,

package/dist/stream-events.d.ts

@@ -1,3 +1,4 @@
+import type { TokenUsage } from "./execution-types.js";
 import type { InteractionRequest } from "./interaction.js";
 import type { DurablePlan } from "./plan.js";
 import type { Part } from "./parts.js";
@@ -7,6 +8,63 @@ export type MessagePartUpdatedEvent = {
     delta?: string;
 };
 export type StreamStatus = "started" | "processing" | "completed" | "failed" | "cancelled";
+export type ChildTaskStatus = "started" | "running" | "completed" | "failed" | "cancelled";
+/**
+ * One observed update of a provider-native child task: a subagent, worker, or
+ * delegated task that the runner started inside the same run.
+ *
+ * Identity rules:
+ * - `childId` is the provider's stable identifier for the child task. Every
+ *   update of one child repeats the same `childId`. A provider that cannot
+ *   report a stable `childId` emits no `child-task` event.
+ * - `parentChildId` names the parent child task. It is absent when the parent
+ *   is the run itself.
+ * - `sourceEventId` is the provider's identifier for this exact update. Two
+ *   events with the same `sourceEventId` are the same update, so a consumer
+ *   applies the first and ignores the rest during replay or reconnect.
+ * - Identity never depends on `raw`. `raw` is an opaque, bounded copy of
+ *   provider fields that have no canonical position.
+ *
+ * Certainty rules:
+ * - `time.ended` and `terminalReason` are present only with a terminal status
+ *   (`completed`, `failed`, `cancelled`).
+ * - `time.updated` and `time.ended` are never earlier than `time.started`.
+ *
+ * Dedupe example for a consumer that rebuilds the child tree from a replayed
+ * stream. Live and replayed streams produce the same tree because identity
+ * comes only from `childId`, `parentChildId`, and `sourceEventId`:
+ *
+ * ```ts
+ * const applied = new Set<string>();
+ * const children = new Map<string, ChildTaskEvent>();
+ * for (const event of events) {
+ *   if (event.type !== "child-task") continue;
+ *   if (applied.has(event.sourceEventId)) continue;
+ *   applied.add(event.sourceEventId);
+ *   children.set(event.childId, event);
+ * }
+ * ```
+ */
+export type ChildTaskEvent = {
+    type: "child-task";
+    childId: string;
+    parentChildId?: string;
+    status: ChildTaskStatus;
+    title?: string;
+    /** Epoch milliseconds reported by the provider. */
+    time: {
+        started: number;
+        updated: number;
+        ended?: number;
+    };
+    /** Runner that executes the child, for example `claude-code`. */
+    runner?: string;
+    model?: string;
+    usage?: TokenUsage;
+    terminalReason?: string;
+    sourceEventId: string;
+    raw?: Record<string, unknown>;
+};
 export type StreamEvent = MessagePartUpdatedEvent | {
     type: "tool-heartbeat";
     toolName: string;
@@ -53,4 +111,4 @@ export type StreamEvent = MessagePartUpdatedEvent | {
 } | {
     type: "plan.submitted";
     plan: DurablePlan;
-};
+} | ChildTaskEvent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -22,6 +22,11 @@
       "types": "./dist/environment-interactive.d.ts",
       "default": "./dist/environment-interactive.js"
     },
+    "./environment-interactive-control": {
+      "import": "./dist/environment-interactive-control.js",
+      "types": "./dist/environment-interactive-control.d.ts",
+      "default": "./dist/environment-interactive-control.js"
+    },
     "./profile": {
       "import": "./dist/agent-profile.js",
       "types": "./dist/agent-profile.d.ts",