@tangle-network/agent-interface 0.45.0 → 0.46.1

package/dist/environment-provider.js

@@ -1,245 +1,3 @@
-import { z } from "zod";
-import { InteractionCapabilitiesSchema, } from "./interaction.js";
-/*
- * Keep the provider contract runtime-validatable. Provider capability data is
- * commonly read from a remote service or adapter configuration, so its static
- * TypeScript type is not a trust boundary.
- */
-const AgentProfileCapabilitiesSchema = z.strictObject({
-    namedProfiles: z.boolean(),
-    /*
-     * Both bits are required with no default: a document that omits either one,
-     * or sends a bare boolean, fails validation instead of being read as
-     * replacement-supported, which for every append-only backend is false.
-     */
-    systemPrompt: z.strictObject({
-        replace: z.boolean(),
-        append: z.boolean(),
-    }),
-    instructions: z.boolean(),
-    tools: z.boolean(),
-    permissions: z.boolean(),
-    mcp: z.boolean(),
-    subagents: z.boolean(),
-    resources: z.strictObject({
-        files: z.boolean(),
-        instructions: z.boolean(),
-        tools: z.boolean().optional(),
-        skills: z.boolean().optional(),
-        agents: z.boolean().optional(),
-        commands: z.boolean().optional(),
-    }),
-    hooks: z.boolean().optional(),
-    modes: z.boolean().optional(),
-    runtimeUpdate: z.boolean(),
-    validation: z.boolean(),
-    extensions: z.array(z.string().min(1)).optional(),
-});
-import { ContextTransferReceiptSchema, NativeContextContinuationAcknowledgementSchema, NativeContextContinuationRequestSchema, nativeContextContinuationAcknowledgementMatches, } from "./portable-context.js";
-import { AgentRunControlRefSchema, CanonicalStreamEventSchema, } from "./runtime-control.js";
-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: z.string().min(1),
-    data: z.record(z.string(), z.unknown()),
-    id: z.string().min(1).optional(),
-    normalized: CanonicalStreamEventSchema.optional(),
-    usage: TokenUsageSchema.optional(),
-    providerEvent: z.unknown().optional(),
-});
-/** Runtime validator for a provider turn returned from durable continuation. */
-export const AgentTurnResultSchema = z.strictObject({
-    text: z.string(),
-    success: z.boolean(),
-    error: z.string().optional(),
-    sessionId: z.string().min(1).optional(),
-    usage: TokenUsageSchema.optional(),
-    metadata: z.record(z.string(), z.unknown()).optional(),
-    events: z.array(AgentEnvironmentEventSchema).optional(),
-    contextTransferReceipt: ContextTransferReceiptSchema.optional(),
-});
-/** Durable provider result for one digest-bound native continuation operation. */
-export const AgentNativeContextContinuationResultSchema = z.union([
-    z
-        .strictObject({
-        acknowledgement: NativeContextContinuationAcknowledgementSchema.and(z.object({ status: z.enum(["accepted", "replayed"]) })),
-        result: AgentTurnResultSchema,
-        /** Exact provider coordinates after the continuation completed. */
-        controlRef: AgentRunControlRefSchema,
-    })
-        .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 result against its exact request and 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 source = parsedRequest.data.run;
-    const current = exactOutcome.controlRef;
-    return (current.provider === source.provider &&
-        current.environmentId === source.environmentId &&
-        current.sessionId === source.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),
-    })
-        .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",
-        });
-    }
-});
+export * from "./environment-requests.js";
+export * from "./environment-exact-process.js";
+export * from "./environment-runtime.js";

package/dist/environment-requests.d.ts

@@ -0,0 +1,70 @@
+import type { AgentProfile } from "./agent-profile.js";
+/** Portable profile reference: inline profile or provider catalog id. */
+export type AgentProfileRef = AgentProfile | string;
+export type AgentEnvironmentStatus = "pending" | "provisioning" | "running" | "stopped" | "failed" | "expired" | "unknown";
+export type AgentSessionStatus = AgentEnvironmentStatus | "completed" | "cancelled";
+export interface WorkspaceRequest {
+    /** Provider-specific environment/template id, for example "universal". */
+    environment?: string;
+    /** Container image or image alias when the provider supports image-backed workspaces. */
+    image?: string;
+    /** Repository to clone or mount before the agent runs. */
+    repoUrl?: string;
+    /** Git ref for {@link repoUrl}. */
+    gitRef?: string;
+    /** Initial working directory inside the environment. */
+    cwd?: string;
+    /** Opaque provider-native workspace fields. */
+    providerOptions?: Record<string, unknown>;
+}
+export interface ResourceRequest {
+    cpu?: number;
+    memoryMb?: number;
+    diskMb?: number;
+    gpu?: string;
+    providerOptions?: Record<string, unknown>;
+}
+export interface AgentEnvironmentQuery {
+    name?: string;
+    metadata?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
+}
+export interface AgentEnvironmentSummary {
+    id: string;
+    provider: string;
+    name?: string;
+    status?: AgentEnvironmentStatus;
+    metadata?: Record<string, unknown>;
+}
+export interface ExecRequest {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface CheckpointRequest {
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CheckpointRef {
+    id: string;
+    provider?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ForkRequest {
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface PlacementInfo {
+    kind: "local" | "sandbox" | "fleet" | "provider";
+    sandboxId?: string;
+    fleetId?: string;
+    machineId?: string;
+    region?: string;
+    providerMetadata?: Record<string, unknown>;
+}

package/dist/environment-requests.js

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