@tangle-network/agent-interface 0.45.0 → 0.46.1

package/dist/environment-runtime.js

@@ -0,0 +1,228 @@
+import { z } from "zod";
+import { InteractionCapabilitiesSchema } from "./interaction.js";
+import { ContextTransferReceiptSchema, ContextTransferRequestSchema, NativeContextContinuationAcknowledgementSchema, NativeContextContinuationRequestSchema, nativeContextContinuationAcknowledgementMatches } from "./portable-context.js";
+import { AgentExactRunControlRefSchema, AgentRunControlRefSchema, CanonicalStreamEventSchema } from "./runtime-control.js";
+import { AgentProfileCapabilitiesSchema } from "./environment-profile-capabilities.js";
+import { boundedIdentifierSchema, boundedJsonRecordSchema, boundedJsonSchema, boundedStringSchema, CONTRACT_MAX_ARRAY_LENGTH } from "./contract-limits.js";
+import { InputPartSchema } from "./portable-context-shared.js";
+export const AgentTurnInputSchema = z.strictObject({
+    prompt: boundedStringSchema.optional(),
+    parts: z.array(InputPartSchema).max(CONTRACT_MAX_ARRAY_LENGTH).optional(),
+    sessionId: boundedIdentifierSchema.optional(),
+    model: boundedIdentifierSchema.optional(),
+    timeoutMs: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+    executionId: boundedIdentifierSchema.optional(),
+    lastEventId: boundedIdentifierSchema.optional(),
+    turnId: boundedIdentifierSchema.optional(),
+    detach: z.boolean().optional(),
+    controlRef: AgentRunControlRefSchema.optional(),
+    contextTransfer: ContextTransferRequestSchema.optional(),
+    nativeContinuation: NativeContextContinuationRequestSchema.optional(),
+    context: boundedJsonRecordSchema.optional(),
+    signal: z.custom().optional(),
+    providerOptions: boundedJsonRecordSchema.optional(),
+});
+const TokenUsageSchema = z.strictObject({
+    inputTokens: z.number().int().nonnegative(),
+    outputTokens: z.number().int().nonnegative(),
+    totalTokens: z.number().int().nonnegative().optional(),
+    cacheReadInputTokens: z.number().int().nonnegative().optional(),
+    cacheCreationInputTokens: z.number().int().nonnegative().optional(),
+    reasoningTokens: z.number().int().nonnegative().optional(),
+    cost: z.number().finite().nonnegative().optional(),
+});
+const AgentEnvironmentEventSchema = z.strictObject({
+    type: boundedIdentifierSchema,
+    data: boundedJsonRecordSchema,
+    id: boundedIdentifierSchema.optional(),
+    normalized: CanonicalStreamEventSchema.optional(),
+    usage: TokenUsageSchema.optional(),
+    providerEvent: boundedJsonSchema.optional(),
+});
+/** Runtime validator for a provider turn returned from durable continuation. */
+export const AgentTurnResultSchema = z.strictObject({
+    text: boundedStringSchema,
+    success: z.boolean(),
+    error: boundedStringSchema.optional(),
+    sessionId: boundedIdentifierSchema.optional(),
+    usage: TokenUsageSchema.optional(),
+    metadata: boundedJsonRecordSchema.optional(),
+    events: z.array(AgentEnvironmentEventSchema).max(CONTRACT_MAX_ARRAY_LENGTH).optional(),
+    contextTransferReceipt: ContextTransferReceiptSchema.optional(),
+});
+/** Durable provider result for one digest-bound native continuation. */
+export const AgentNativeContextContinuationResultSchema = z.union([
+    z
+        .strictObject({
+        acknowledgement: NativeContextContinuationAcknowledgementSchema.and(z.object({ status: z.enum(["accepted", "replayed"]) })),
+        result: AgentTurnResultSchema,
+        controlRef: AgentExactRunControlRefSchema,
+    })
+        .superRefine((outcome, refinement) => {
+        if (outcome.result.contextTransferReceipt !== undefined) {
+            refinement.addIssue({
+                code: "custom",
+                path: ["result", "contextTransferReceipt"],
+                message: "native continuation cannot return a context transfer receipt",
+            });
+        }
+    }),
+    z
+        .strictObject({
+        acknowledgement: NativeContextContinuationAcknowledgementSchema.and(z.object({
+            status: z.enum([
+                "conflict",
+                "boundary_mismatch",
+                "unverified",
+                "unknown_session",
+                "transport_failure",
+            ]),
+        })),
+    })
+        .superRefine((outcome, refinement) => {
+        if (outcome.acknowledgement.status === "transport_failure" &&
+            outcome.acknowledgement.retryable !== true) {
+            refinement.addIssue({
+                code: "custom",
+                path: ["acknowledgement", "retryable"],
+                message: "a durable native continuation transport failure must be retryable",
+            });
+        }
+    }),
+]);
+/** Cross-check a successful native continuation against its retained session. */
+export function agentNativeContextContinuationResultMatchesRequest(request, outcome) {
+    const parsedRequest = NativeContextContinuationRequestSchema.safeParse(request);
+    const parsedOutcome = AgentNativeContextContinuationResultSchema.safeParse(outcome);
+    if (!parsedRequest.success || !parsedOutcome.success)
+        return false;
+    const exactOutcome = parsedOutcome.data;
+    if (exactOutcome.acknowledgement.status !== "accepted" &&
+        exactOutcome.acknowledgement.status !== "replayed")
+        return false;
+    if (!("result" in exactOutcome) || !("controlRef" in exactOutcome))
+        return false;
+    if (!nativeContextContinuationAcknowledgementMatches(parsedRequest.data, exactOutcome.acknowledgement))
+        return false;
+    const current = exactOutcome.controlRef;
+    return (current.provider === request.run.provider &&
+        current.environmentId === request.run.environmentId &&
+        current.sessionId === request.run.sessionId &&
+        (exactOutcome.result.sessionId === undefined ||
+            exactOutcome.result.sessionId === current.sessionId));
+}
+/** Strict runtime validator for provider capability negotiation. */
+export const AgentEnvironmentCapabilitiesSchema = z
+    .strictObject({
+    profile: AgentProfileCapabilitiesSchema,
+    streaming: z.strictObject({
+        live: z.boolean(),
+        replay: z.boolean(),
+        detach: z.boolean(),
+        turnIdempotency: z.boolean(),
+    }),
+    sessions: z.strictObject({
+        continue: z.boolean(),
+        list: z.boolean(),
+        messages: z.boolean(),
+    }),
+    retainedControl: z
+        .strictObject({
+        exactRunIdentity: z.boolean(),
+        resultIdentity: z.boolean(),
+        eventIdentity: z.boolean(),
+        cancellationIdempotency: z.boolean(),
+    })
+        .optional(),
+    nativeContinuation: z
+        .strictObject({
+        atomicBoundary: z.boolean(),
+        requestIdempotency: z.boolean(),
+    })
+        .optional(),
+    interactions: InteractionCapabilitiesSchema.optional(),
+    workspace: z.strictObject({
+        read: z.boolean(),
+        write: z.boolean(),
+        exec: z.boolean(),
+        git: z.boolean(),
+        upload: z.boolean(),
+        download: z.boolean(),
+    }),
+    branching: z.strictObject({
+        checkpoint: z.boolean(),
+        fork: z.boolean(),
+        retrySafe: z.boolean().optional(),
+        lookup: z.boolean().optional(),
+        cleanup: z.boolean().optional(),
+    }),
+    placement: z.boolean(),
+    usage: z.boolean(),
+    confidential: z.boolean(),
+    exactProcess: z
+        .strictObject({
+        egress: z
+            .array(z.enum(["blocked", "strict"]))
+            .min(1)
+            .max(CONTRACT_MAX_ARRAY_LENGTH),
+    })
+        .optional(),
+})
+    .superRefine((capabilities, refinement) => {
+    if (capabilities.retainedControl !== undefined &&
+        (!capabilities.retainedControl.exactRunIdentity ||
+            !capabilities.retainedControl.resultIdentity ||
+            !capabilities.retainedControl.eventIdentity ||
+            !capabilities.retainedControl.cancellationIdempotency ||
+            !capabilities.streaming.replay ||
+            !capabilities.streaming.detach ||
+            !capabilities.streaming.turnIdempotency ||
+            !capabilities.sessions.continue)) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["retainedControl"],
+            message: "retained control requires exact run, result, event, cancellation, replay, detach, turn, and session identity together",
+        });
+    }
+    if (capabilities.nativeContinuation !== undefined &&
+        (!capabilities.nativeContinuation.atomicBoundary ||
+            !capabilities.nativeContinuation.requestIdempotency ||
+            !capabilities.sessions.continue)) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["nativeContinuation"],
+            message: "native continuation requires session continuation, atomic boundary admission, and request idempotency together",
+        });
+    }
+    const durableBranching = [
+        capabilities.branching.retrySafe ?? false,
+        capabilities.branching.lookup ?? false,
+        capabilities.branching.cleanup ?? false,
+    ];
+    if (durableBranching.some(Boolean) &&
+        (!durableBranching.every(Boolean) ||
+            !capabilities.branching.checkpoint ||
+            !capabilities.branching.fork)) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["branching"],
+            message: "retry-safe branching requires checkpoint, fork, lookup, and cleanup together",
+        });
+    }
+    const egress = capabilities.exactProcess?.egress;
+    if (egress && new Set(egress).size !== egress.length) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["exactProcess", "egress"],
+            message: "exact process egress modes must be unique",
+        });
+    }
+    const extensions = capabilities.profile.extensions;
+    if (extensions && new Set(extensions).size !== extensions.length) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["profile", "extensions"],
+            message: "profile extension namespaces must be unique",
+        });
+    }
+});

package/dist/execution-types.d.ts

@@ -0,0 +1,50 @@
+import type { AgentExecutionOutcome, PlanContinuation } from "./plan.js";
+import type { InputPart } from "./parts.js";
+import type { ProviderConfig } from "./provider-config.js";
+import type { InteractionExecutionBinding } from "./interaction-envelope.js";
+export type ToolInvocation = {
+    toolName: string;
+    input: unknown;
+    result?: unknown;
+    isError?: boolean;
+};
+export type TokenUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens?: number;
+    cacheReadInputTokens?: number;
+    cacheCreationInputTokens?: number;
+    reasoningTokens?: number;
+    cost?: number;
+};
+export type ExecutionTiming = {
+    startedAt: number;
+    completedAt: number;
+    durationMs: number;
+};
+export type AgentExecutionInput = {
+    message?: string;
+    parts?: InputPart[];
+    systemPrompt: string;
+    userId?: string;
+    traceId?: string;
+    sessionId?: string;
+    /** Exact run coordinates required when this turn can emit interactions. */
+    interactionBinding?: InteractionExecutionBinding;
+    workspaceRoot?: string;
+    abortSignal?: AbortSignal;
+    headers?: Record<string, string>;
+    model?: ProviderConfig["model"];
+    turnId?: string;
+    planContinuation?: PlanContinuation;
+};
+export type AgentExecutionResult = {
+    outcome: AgentExecutionOutcome;
+    text: string;
+    toolInvocations: ToolInvocation[];
+    reasoning?: string[];
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+    tokenUsage?: TokenUsage;
+    timing?: ExecutionTiming;
+};

package/dist/execution-types.js

@@ -0,0 +1 @@
+export {};

package/dist/host-services.d.ts

@@ -0,0 +1,91 @@
+import type { BackendMessage } from "./backend-message.js";
+import type { AgentExecutionResult } from "./execution-types.js";
+import type { Part } from "./parts.js";
+import type { SdkPlanHost } from "./plan.js";
+import type { ProviderConfig } from "./provider-config.js";
+export type MemoryEntry = {
+    id: string;
+    type: "summary" | "fact" | "note";
+    content: string;
+    createdAt: string;
+};
+export type MemoryEntryInput = Omit<MemoryEntry, "id" | "createdAt">;
+export interface SdkMemoryHost {
+    list(sessionId: string): Promise<MemoryEntry[]>;
+    remember(sessionId: string, entry: MemoryEntryInput): Promise<void>;
+    format(entries: MemoryEntry[]): string;
+}
+export type ToolExecutionContext = {
+    workspaceRoot?: string;
+};
+export type ToolDefinition = {
+    name: string;
+    description: string;
+    instruction?: string;
+    inputSchema: unknown;
+    inputSchemaJson: Record<string, unknown>;
+    outputSchema?: unknown;
+    outputSchemaJson?: Record<string, unknown>;
+    handler: (input: unknown, context: ToolExecutionContext) => Promise<unknown>;
+};
+export interface SdkToolHost {
+    buildPromptBlock(): string;
+    registerInstruction?(instruction: string, key?: string): void;
+    clear?(): void;
+    getRegisteredTools(): ToolDefinition[];
+}
+export interface SdkRecorder {
+    recordUserMessage(parts: BackendMessage["parts"]): Promise<void>;
+    appendAssistantParts(parts: BackendMessage["parts"]): Promise<void>;
+    setSessionId(sessionId?: string): Promise<void>;
+    recordAssistantPartUpdate?(part: Part, delta?: string): Promise<void>;
+    setTurnId?(turnId: string): void;
+    markTurnCompleted?(payload?: {
+        result?: Record<string, unknown>;
+        [extra: string]: unknown;
+    }): Promise<void>;
+    markTurnInterrupted?(payload?: {
+        reason?: string;
+        [extra: string]: unknown;
+    }): Promise<void>;
+    findCompletedTurn?(turnId: string): Promise<AgentExecutionResult | null>;
+}
+export type TraceEventInput = {
+    type: "message.part.updated";
+    part: Part;
+    delta?: string;
+} | {
+    type: "message.updated";
+    text?: string;
+    finalText?: string;
+    tokenUsage?: Record<string, unknown>;
+    timing?: Record<string, unknown>;
+    toolInvocations?: unknown[];
+    metadata?: Record<string, unknown>;
+} | {
+    type: "error";
+    category: "runtime" | "syntax" | "type" | "network" | "timeout" | "unknown";
+    message: string;
+    stack?: string;
+    code?: string;
+    source?: string;
+} | {
+    type: "custom";
+    name: string;
+    data: Record<string, unknown>;
+};
+export interface SdkTraceContext {
+    addEvent(event: TraceEventInput): void;
+    addSignal(signal: string, metadata?: Record<string, unknown>): void;
+    complete(metadata?: Record<string, unknown>): void;
+    fail(error: string | Error, metadata?: Record<string, unknown>): void;
+    trackSubAgent?(childSessionId: string, agentType?: string): void;
+}
+export type SdkHostServices = {
+    memoryHost: SdkMemoryHost;
+    toolHost: SdkToolHost;
+    planHost: SdkPlanHost;
+    recorder: SdkRecorder;
+    providerConfig: ProviderConfig;
+    traceContext?: SdkTraceContext;
+};

package/dist/host-services.js

@@ -0,0 +1 @@
+export {};