@tangle-network/agent-interface 1.2.0 → 1.3.0

package/dist/environment-interactive-start.d.ts

@@ -0,0 +1,238 @@
+import { z } from "zod";
+import { type AgentInteractiveSessionRef } from "./environment-interactive-control.js";
+import { type AgentExactRunControlRef } from "./runtime-control.js";
+declare const AgentInteractiveSessionRunCoordinatesSchema: z.ZodObject<{
+    provider: z.ZodString;
+    environmentId: z.ZodString;
+    sessionId: z.ZodString;
+    executionId: z.ZodString;
+}, z.core.$strict>;
+export type AgentInteractiveSessionRunCoordinates = z.infer<typeof AgentInteractiveSessionRunCoordinatesSchema>;
+/**
+ * Start one native coding-agent TUI from caller-owned request material.
+ *
+ * The provider owns profile materialization and returns its preparation receipt
+ * in the resulting reference. Replaying the same exact request/run returns the
+ * same reference, even after the process exits; changed material cannot reuse it.
+ */
+export declare const AgentInteractiveSessionStartSchema: z.ZodObject<{
+    run: z.ZodObject<{
+        runId: z.ZodString;
+        provider: z.ZodString;
+        environmentId: z.ZodString;
+        sessionId: z.ZodString;
+        executionId: z.ZodString;
+        requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>;
+    profile: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        prompt: z.ZodOptional<z.ZodObject<{
+            systemPrompt: z.ZodOptional<z.ZodString>;
+            appendSystemPrompt: z.ZodOptional<z.ZodString>;
+            instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        model: z.ZodOptional<z.ZodObject<{
+            default: z.ZodOptional<z.ZodString>;
+            small: z.ZodOptional<z.ZodString>;
+            provider: z.ZodOptional<z.ZodString>;
+            reasoningEffort: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                minimal: "minimal";
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+                ultracode: "ultracode";
+            }>>;
+            maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+            maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+            maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
+            metadata: z.ZodOptional<z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>>;
+        }, z.core.$strict>>;
+        harness: z.ZodOptional<z.ZodEnum<{
+            "claude-code": "claude-code";
+            nanoclaw: "nanoclaw";
+            codex: "codex";
+            opencode: "opencode";
+            "kimi-code": "kimi-code";
+            pi: "pi";
+            prime: "prime";
+            gemini: "gemini";
+            hermes: "hermes";
+            openclaw: "openclaw";
+            amp: "amp";
+            "factory-droids": "factory-droids";
+            forge: "forge";
+            cursor: "cursor";
+            acp: "acp";
+            "cli-base": "cli-base";
+        }>>;
+        permissions: z.ZodOptional<z.ZodType<Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">>, unknown, z.core.$ZodTypeInternals<Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">>, unknown>>>;
+        tools: z.ZodOptional<z.ZodType<Record<string, boolean>, unknown, z.core.$ZodTypeInternals<Record<string, boolean>, unknown>>>;
+        mcp: z.ZodOptional<z.ZodType<Record<string, import("./agent-profile.js").AgentProfileMcpServer>, unknown, z.core.$ZodTypeInternals<Record<string, import("./agent-profile.js").AgentProfileMcpServer>, unknown>>>;
+        connections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            connectionId: z.ZodString;
+            capabilities: z.ZodArray<z.ZodString>;
+            alias: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        subagents: z.ZodOptional<z.ZodType<Record<string, {
+            description?: string | undefined;
+            prompt?: string | undefined;
+            model?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            maxSteps?: number | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown, z.core.$ZodTypeInternals<Record<string, {
+            description?: string | undefined;
+            prompt?: string | undefined;
+            model?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            maxSteps?: number | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown>>>;
+        resources: z.ZodOptional<z.ZodObject<{
+            files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                resource: z.ZodUnion<readonly [z.ZodObject<{
+                    kind: z.ZodLiteral<"inline">;
+                    name: z.ZodString;
+                    content: z.ZodString;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"github">;
+                    repository: z.ZodOptional<z.ZodString>;
+                    path: z.ZodString;
+                    ref: z.ZodOptional<z.ZodString>;
+                    name: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>]>;
+                executable: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>>;
+            tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            skills: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            agents: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            commands: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            instructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>]>>;
+            failOnError: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        hooks: z.ZodOptional<z.ZodType<Record<string, {
+            command: string;
+            timeoutMs?: number | undefined;
+            blocking?: boolean | undefined;
+            matcher?: string | undefined;
+            env?: Record<string, {
+                kind: "public";
+                value: string;
+            } | {
+                kind: "secret-ref";
+                key: string;
+                format?: "raw" | "bearer" | undefined;
+            }> | undefined;
+        }[]>, unknown, z.core.$ZodTypeInternals<Record<string, {
+            command: string;
+            timeoutMs?: number | undefined;
+            blocking?: boolean | undefined;
+            matcher?: string | undefined;
+            env?: Record<string, {
+                kind: "public";
+                value: string;
+            } | {
+                kind: "secret-ref";
+                key: string;
+                format?: "raw" | "bearer" | undefined;
+            }> | undefined;
+        }[]>, unknown>>>;
+        modes: z.ZodOptional<z.ZodType<Record<string, {
+            description?: string | undefined;
+            model?: string | undefined;
+            prompt?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown, z.core.$ZodTypeInternals<Record<string, {
+            description?: string | undefined;
+            model?: string | undefined;
+            prompt?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown>>>;
+        confidential: z.ZodOptional<z.ZodObject<{
+            tee: z.ZodOptional<z.ZodString>;
+            attestationNonce: z.ZodOptional<z.ZodString>;
+            sealed: z.ZodOptional<z.ZodBoolean>;
+            attestationRefresh: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        metadata: z.ZodOptional<z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>>;
+        extensions: z.ZodOptional<z.ZodType<Record<string, Record<string, unknown> | undefined>, unknown, z.core.$ZodTypeInternals<Record<string, Record<string, unknown> | undefined>, unknown>>>;
+    }, z.core.$strict>;
+    requestedProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    initialPrompt: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+    cols: z.ZodOptional<z.ZodNumber>;
+    rows: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type AgentInteractiveSessionStart = z.infer<typeof AgentInteractiveSessionStartSchema>;
+export type AgentInteractiveSessionStartInput = Omit<AgentInteractiveSessionStart, "run">;
+/** Digest the exact process-start request independently of its derived run id. */
+export declare function agentInteractiveSessionRequestDigest(coordinates: AgentInteractiveSessionRunCoordinates, input: AgentInteractiveSessionStartInput): `sha256:${string}`;
+/** Mint the one exact run reference a provider must acknowledge for this start. */
+export declare function agentInteractiveSessionRunRef(coordinates: AgentInteractiveSessionRunCoordinates, input: AgentInteractiveSessionStartInput): AgentExactRunControlRef;
+/** Parse a start request and prove its profile identity before provider work. */
+export declare function exactAgentInteractiveSessionStart(value: AgentInteractiveSessionStart): AgentInteractiveSessionStart;
+/** Prove that a provider returned the exact run and preparation receipt requested. */
+export declare function agentInteractiveSessionRefMatchesStart(request: AgentInteractiveSessionStart, ref: AgentInteractiveSessionRef): boolean;
+export {};

package/dist/environment-interactive-start.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { canonicalCandidateDigest, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+import { canonicalAgentProfileDigest } from "./agent-execution-preparation.js";
+import { boundedIdentifierSchema, boundedStringSchema, } from "./contract-limits.js";
+import { AgentInteractiveSessionRefSchema, } from "./environment-interactive-control.js";
+import { agentInteractiveDimensionSchema as interactiveDimensionSchema, sameAgentExactRun as sameExactRun, } from "./environment-interactive-shared.js";
+import { agentProfileSchema } from "./profile-schema.js";
+import { AgentExactRunControlRefSchema, } from "./runtime-control.js";
+const AgentInteractiveSessionRunCoordinatesSchema = z.strictObject({
+    provider: boundedIdentifierSchema,
+    environmentId: boundedIdentifierSchema,
+    sessionId: boundedIdentifierSchema,
+    executionId: boundedIdentifierSchema,
+});
+/**
+ * Start one native coding-agent TUI from caller-owned request material.
+ *
+ * The provider owns profile materialization and returns its preparation receipt
+ * in the resulting reference. Replaying the same exact request/run returns the
+ * same reference, even after the process exits; changed material cannot reuse it.
+ */
+export const AgentInteractiveSessionStartSchema = z.strictObject({
+    run: AgentExactRunControlRefSchema,
+    profile: agentProfileSchema,
+    requestedProfileDigest: sha256DigestSchema,
+    initialPrompt: boundedStringSchema.optional(),
+    cwd: boundedStringSchema.min(1).optional(),
+    cols: interactiveDimensionSchema.optional(),
+    rows: interactiveDimensionSchema.optional(),
+});
+/** Digest the exact process-start request independently of its derived run id. */
+export function agentInteractiveSessionRequestDigest(coordinates, input) {
+    const exactCoordinates = AgentInteractiveSessionRunCoordinatesSchema.parse(coordinates);
+    const exactInput = AgentInteractiveSessionStartSchema.omit({ run: true }).parse(input);
+    return canonicalCandidateDigest({
+        kind: "agent-interactive-session-start.v1",
+        run: exactCoordinates,
+        requestedProfileDigest: exactInput.requestedProfileDigest,
+        ...(exactInput.initialPrompt === undefined
+            ? {}
+            : { initialPrompt: exactInput.initialPrompt }),
+        ...(exactInput.cwd === undefined ? {} : { cwd: exactInput.cwd }),
+        ...(exactInput.cols === undefined ? {} : { cols: exactInput.cols }),
+        ...(exactInput.rows === undefined ? {} : { rows: exactInput.rows }),
+    });
+}
+/** Mint the one exact run reference a provider must acknowledge for this start. */
+export function agentInteractiveSessionRunRef(coordinates, input) {
+    const exactCoordinates = AgentInteractiveSessionRunCoordinatesSchema.parse(coordinates);
+    const requestDigest = agentInteractiveSessionRequestDigest(exactCoordinates, input);
+    return AgentExactRunControlRefSchema.parse({
+        ...exactCoordinates,
+        runId: `interactive-run-${requestDigest.slice("sha256:".length)}`,
+        requestDigest,
+    });
+}
+/** Parse a start request and prove its profile identity before provider work. */
+export function exactAgentInteractiveSessionStart(value) {
+    const parsed = AgentInteractiveSessionStartSchema.parse(value);
+    if (parsed.profile.harness === undefined) {
+        throw new Error("interactive agent sessions require AgentProfile.harness");
+    }
+    const digest = canonicalAgentProfileDigest(parsed.profile);
+    if (digest !== parsed.requestedProfileDigest) {
+        throw new Error("interactive agent session requested profile digest does not match its profile");
+    }
+    const { run, ...input } = parsed;
+    const expectedRun = agentInteractiveSessionRunRef(runCoordinates(run), input);
+    if (!sameExactRun(run, expectedRun)) {
+        throw new Error("interactive agent session run identity does not match its start request");
+    }
+    return parsed;
+}
+/** Prove that a provider returned the exact run and preparation receipt requested. */
+export function agentInteractiveSessionRefMatchesStart(request, ref) {
+    const parsedRequest = AgentInteractiveSessionStartSchema.safeParse(request);
+    const parsedRef = AgentInteractiveSessionRefSchema.safeParse(ref);
+    if (!parsedRequest.success || !parsedRef.success)
+        return false;
+    const requestedHarness = parsedRequest.data.profile.harness;
+    if (requestedHarness === undefined)
+        return false;
+    return (parsedRef.data.preparationReceipt.authoredProfileDigest ===
+        parsedRequest.data.requestedProfileDigest &&
+        parsedRef.data.preparationReceipt.harness === requestedHarness &&
+        sameExactRun(parsedRef.data.run, parsedRequest.data.run));
+}
+function runCoordinates(run) {
+    return {
+        provider: run.provider,
+        environmentId: run.environmentId,
+        sessionId: run.sessionId,
+        executionId: run.executionId,
+    };
+}