@tangle-network/agent-interface 0.40.0 → 0.41.0

package/dist/profile-schema.d.ts

@@ -325,6 +325,8 @@ export declare const agentProfileSchema: z.ZodObject<{
         openclaw: "openclaw";
         amp: "amp";
         "factory-droids": "factory-droids";
+        forge: "forge";
+        cursor: "cursor";
         acp: "acp";
         "cli-base": "cli-base";
     }>>;

package/dist/runtime-control.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import type { StreamEvent } from "./index.js";
+/** Provider-neutral coordinates sufficient to recreate control of one run. */
+export interface AgentRunControlRef {
+    runId: string;
+    provider: string;
+    environmentId: string;
+    sessionId?: string;
+    executionId?: string;
+}
+export declare const AgentRunControlRefSchema: z.ZodObject<{
+    runId: z.ZodString;
+    provider: z.ZodString;
+    environmentId: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+    executionId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Runtime validator for every member of the existing canonical event union. */
+export declare const CanonicalStreamEventSchema: z.ZodType<StreamEvent>;
+/** Ordered, replayable envelope around the existing canonical event union. */
+export interface RuntimeEventEnvelope {
+    runId: string;
+    eventId: string;
+    sequence: number;
+    cursor?: string;
+    occurredAt?: string;
+    receivedAt: string;
+    event: StreamEvent;
+}
+export declare const RuntimeEventEnvelopeSchema: z.ZodObject<{
+    runId: z.ZodString;
+    eventId: z.ZodString;
+    sequence: z.ZodNumber;
+    cursor: z.ZodOptional<z.ZodString>;
+    occurredAt: z.ZodOptional<z.ZodISODateTime>;
+    receivedAt: z.ZodISODateTime;
+    event: z.ZodType<StreamEvent, unknown, z.core.$ZodTypeInternals<StreamEvent, unknown>>;
+}, z.core.$strict>;

package/dist/runtime-control.js

@@ -0,0 +1,161 @@
+import { z } from "zod";
+import { InteractionRequestSchema } from "./interaction.js";
+import { DurablePlanSchema } from "./plan.js";
+const stableIdSchema = z
+    .string()
+    .min(1)
+    .max(512)
+    .refine((value) => value.trim() === value, "identifier cannot have outer whitespace");
+export const AgentRunControlRefSchema = z.strictObject({
+    runId: stableIdSchema,
+    provider: stableIdSchema,
+    environmentId: stableIdSchema,
+    sessionId: stableIdSchema.optional(),
+    executionId: stableIdSchema.optional(),
+});
+const unknownRecordSchema = z.record(z.string(), z.unknown());
+const partBase = {
+    id: stableIdSchema,
+    sessionID: stableIdSchema,
+    messageID: stableIdSchema,
+};
+const toolTimeSchema = z.strictObject({
+    start: z.number().finite(),
+    end: z.number().finite().optional(),
+});
+const toolStateSchema = z.discriminatedUnion("status", [
+    z.strictObject({
+        status: z.literal("pending"),
+        input: unknownRecordSchema,
+        raw: z.string().optional(),
+    }),
+    z.strictObject({
+        status: z.literal("running"),
+        input: unknownRecordSchema,
+        title: z.string().optional(),
+        metadata: unknownRecordSchema.optional(),
+        time: z.strictObject({ start: z.number().finite() }).optional(),
+    }),
+    z.strictObject({
+        status: z.literal("completed"),
+        input: unknownRecordSchema,
+        output: z.unknown(),
+        title: z.string().optional(),
+        metadata: unknownRecordSchema.optional(),
+        time: z.strictObject({
+            start: z.number().finite(),
+            end: z.number().finite(),
+        }).optional(),
+    }),
+    z.strictObject({
+        status: z.enum(["error", "failed"]),
+        input: unknownRecordSchema,
+        error: z.string().optional(),
+        output: z.unknown().optional(),
+        metadata: unknownRecordSchema.optional(),
+        time: toolTimeSchema.optional(),
+    }),
+]);
+const partSchema = z.discriminatedUnion("type", [
+    z.strictObject({ ...partBase, type: z.literal("text"), text: z.string() }),
+    z.strictObject({
+        ...partBase,
+        type: z.literal("tool"),
+        callID: stableIdSchema.optional(),
+        tool: stableIdSchema,
+        state: toolStateSchema,
+        metadata: unknownRecordSchema.optional(),
+    }),
+    z.strictObject({
+        ...partBase,
+        type: z.literal("reasoning"),
+        text: z.string(),
+    }),
+    z.strictObject({
+        ...partBase,
+        type: z.literal("file"),
+        filename: z.string().optional(),
+        mediaType: z.string().optional(),
+        url: z.string().optional(),
+    }),
+    z.strictObject({
+        ...partBase,
+        type: z.literal("subtask"),
+        prompt: z.string(),
+        description: z.string(),
+        agent: stableIdSchema,
+    }),
+]);
+/** Runtime validator for every member of the existing canonical event union. */
+export const CanonicalStreamEventSchema = z.discriminatedUnion("type", [
+    z.strictObject({
+        type: z.literal("message.part.updated"),
+        part: partSchema,
+        delta: z.string().optional(),
+    }),
+    z.strictObject({
+        type: z.literal("tool-heartbeat"),
+        toolName: stableIdSchema,
+        partId: stableIdSchema,
+        elapsedMs: z.number().finite().nonnegative(),
+    }),
+    z.strictObject({
+        type: z.literal("tool-slow"),
+        toolName: stableIdSchema,
+        partId: stableIdSchema,
+        elapsedMs: z.number().finite().nonnegative(),
+        thresholdMs: z.number().finite().nonnegative(),
+    }),
+    z.strictObject({
+        type: z.literal("model-processing"),
+        phase: z.enum(["tool-result", "generating", "thinking"]),
+        toolName: stableIdSchema.optional(),
+        elapsedMs: z.number().finite().nonnegative().optional(),
+    }),
+    z.strictObject({
+        type: z.literal("status"),
+        status: z.enum(["started", "processing", "completed", "failed"]),
+        detail: z.string().optional(),
+    }),
+    z.strictObject({
+        type: z.literal("warning"),
+        code: stableIdSchema,
+        message: z.string(),
+    }),
+    z.strictObject({
+        type: z.literal("raw"),
+        backend: stableIdSchema,
+        event: z.unknown(),
+    }),
+    z.strictObject({
+        type: z.literal("session.updated"),
+        sessionId: stableIdSchema,
+        title: z.string().optional(),
+        time: z.strictObject({
+            created: z.number().finite().optional(),
+            updated: z.number().finite().optional(),
+        }).optional(),
+    }),
+    z.strictObject({
+        type: z.literal("interaction"),
+        request: InteractionRequestSchema,
+    }),
+    z.strictObject({
+        type: z.literal("interaction.cancel"),
+        id: stableIdSchema,
+        reason: z.string().optional(),
+    }),
+    z.strictObject({
+        type: z.literal("plan.submitted"),
+        plan: DurablePlanSchema,
+    }),
+]);
+export const RuntimeEventEnvelopeSchema = z.strictObject({
+    runId: stableIdSchema,
+    eventId: stableIdSchema,
+    sequence: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    cursor: stableIdSchema.optional(),
+    occurredAt: z.iso.datetime().optional(),
+    receivedAt: z.iso.datetime(),
+    event: CanonicalStreamEventSchema,
+});

package/dist/workspace-branching.d.ts

@@ -0,0 +1,251 @@
+import { z } from "zod";
+import type { Sha256Digest } from "./agent-candidate.js";
+import type { PlacementInfo } from "./environment-provider.js";
+import { type AgentRunControlRef } from "./runtime-control.js";
+export interface WorkspaceCheckpointMaterial {
+    source: AgentRunControlRef;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface WorkspaceCheckpointRequest extends WorkspaceCheckpointMaterial {
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+}
+export declare function workspaceCheckpointRequestDigest(material: WorkspaceCheckpointMaterial): Sha256Digest;
+export declare const WorkspaceCheckpointRequestSchema: z.ZodObject<{
+    source: z.ZodObject<{
+        runId: z.ZodString;
+        provider: z.ZodString;
+        environmentId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        executionId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    name: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    idempotencyKey: z.ZodString;
+    requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+}, z.core.$strict>;
+export interface WorkspaceCheckpointRef {
+    checkpointId: string;
+    provider: string;
+    source: AgentRunControlRef;
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}
+export declare const WorkspaceCheckpointRefSchema: z.ZodObject<{
+    checkpointId: z.ZodString;
+    provider: z.ZodString;
+    source: z.ZodObject<{
+        runId: z.ZodString;
+        provider: z.ZodString;
+        environmentId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        executionId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    idempotencyKey: z.ZodString;
+    requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    createdAt: z.ZodISODateTime;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$strict>;
+export type WorkspaceCheckpointResult = {
+    status: "created" | "replayed";
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+    checkpoint: WorkspaceCheckpointRef;
+} | {
+    status: "conflict";
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+    existingRequestDigest: Sha256Digest;
+} | {
+    status: "unknown";
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+    message: string;
+    retryable: boolean;
+};
+export declare const WorkspaceCheckpointResultSchema: z.ZodType<WorkspaceCheckpointResult>;
+export declare const WorkspaceOperationLookupRequestSchema: z.ZodObject<{
+    idempotencyKey: z.ZodString;
+    requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+}, z.core.$strict>;
+export type WorkspaceOperationLookupRequest = z.infer<typeof WorkspaceOperationLookupRequestSchema>;
+export type WorkspaceCheckpointLookupResult = {
+    status: "found";
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+    checkpoint: WorkspaceCheckpointRef;
+} | {
+    status: "not_found";
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+} | {
+    status: "conflict";
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+    existingRequestDigest: Sha256Digest;
+} | {
+    status: "unknown";
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+    message: string;
+    retryable: boolean;
+};
+export declare const WorkspaceCheckpointLookupResultSchema: z.ZodType<WorkspaceCheckpointLookupResult>;
+export interface WorkspaceForkMaterial {
+    checkpoint: WorkspaceCheckpointRef;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface WorkspaceForkRequest extends WorkspaceForkMaterial {
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+}
+export declare function workspaceForkRequestDigest(material: WorkspaceForkMaterial): Sha256Digest;
+export declare const WorkspaceForkRequestSchema: z.ZodObject<{
+    checkpoint: z.ZodObject<{
+        checkpointId: z.ZodString;
+        provider: z.ZodString;
+        source: z.ZodObject<{
+            runId: z.ZodString;
+            provider: z.ZodString;
+            environmentId: z.ZodString;
+            sessionId: z.ZodOptional<z.ZodString>;
+            executionId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        idempotencyKey: z.ZodString;
+        requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        createdAt: z.ZodISODateTime;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$strict>;
+    name: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    idempotencyKey: z.ZodString;
+    requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+}, z.core.$strict>;
+export interface ForkedEnvironmentRef {
+    provider: string;
+    environmentId: string;
+    sourceCheckpointId: string;
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+    createdAt: string;
+    placement?: PlacementInfo;
+    confidential: boolean;
+    metadata?: Record<string, unknown>;
+}
+export declare const ForkedEnvironmentRefSchema: z.ZodObject<{
+    provider: z.ZodString;
+    environmentId: z.ZodString;
+    sourceCheckpointId: z.ZodString;
+    idempotencyKey: z.ZodString;
+    requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    createdAt: z.ZodISODateTime;
+    placement: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            provider: "provider";
+            local: "local";
+            sandbox: "sandbox";
+            fleet: "fleet";
+        }>;
+        sandboxId: z.ZodOptional<z.ZodString>;
+        fleetId: z.ZodOptional<z.ZodString>;
+        machineId: z.ZodOptional<z.ZodString>;
+        region: z.ZodOptional<z.ZodString>;
+        providerMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$strict>>;
+    confidential: z.ZodBoolean;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$strict>;
+export type WorkspaceForkResult = {
+    status: "created" | "replayed";
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+    environment: ForkedEnvironmentRef;
+} | {
+    status: "conflict";
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+    existingRequestDigest: Sha256Digest;
+} | {
+    status: "unknown";
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+    message: string;
+    retryable: boolean;
+};
+export declare const WorkspaceForkResultSchema: z.ZodType<WorkspaceForkResult>;
+export type WorkspaceForkLookupResult = {
+    status: "found";
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+    environment: ForkedEnvironmentRef;
+} | {
+    status: "not_found";
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+} | {
+    status: "conflict";
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+    existingRequestDigest: Sha256Digest;
+} | {
+    status: "unknown";
+    idempotencyKey: string;
+    requestDigest: Sha256Digest;
+    message: string;
+    retryable: boolean;
+};
+export declare const WorkspaceForkLookupResultSchema: z.ZodType<WorkspaceForkLookupResult>;
+export declare const WorkspaceCleanupRequestSchema: z.ZodObject<{
+    operationId: z.ZodString;
+    targetId: z.ZodString;
+    provider: z.ZodString;
+}, z.core.$strict>;
+export type WorkspaceCleanupRequest = z.infer<typeof WorkspaceCleanupRequestSchema>;
+export declare const WorkspaceCleanupAcknowledgementSchema: z.ZodObject<{
+    operationId: z.ZodString;
+    targetId: z.ZodString;
+    provider: z.ZodString;
+    status: z.ZodEnum<{
+        unknown: "unknown";
+        conflict: "conflict";
+        transport_failure: "transport_failure";
+        deleted: "deleted";
+        already_absent: "already_absent";
+        in_use: "in_use";
+    }>;
+    message: z.ZodOptional<z.ZodString>;
+    retryable: z.ZodOptional<z.ZodBoolean>;
+    blockingTargetIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type WorkspaceCleanupAcknowledgement = z.infer<typeof WorkspaceCleanupAcknowledgementSchema>;
+/** Optional durable workspace branch operations implemented by capable providers. */
+export interface AgentWorkspaceBranching {
+    checkpoint(request: WorkspaceCheckpointRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<WorkspaceCheckpointResult>;
+    lookupCheckpoint(request: WorkspaceOperationLookupRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<WorkspaceCheckpointLookupResult>;
+    deleteCheckpoint(request: WorkspaceCleanupRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<WorkspaceCleanupAcknowledgement>;
+    fork(request: WorkspaceForkRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<WorkspaceForkResult>;
+    lookupFork(request: WorkspaceOperationLookupRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<WorkspaceForkLookupResult>;
+    destroyFork(request: WorkspaceCleanupRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<WorkspaceCleanupAcknowledgement>;
+}
+/** Bind a checkpoint result to the exact request before using the resource. */
+export declare function workspaceCheckpointResultMatchesRequest(request: WorkspaceCheckpointRequest, result: WorkspaceCheckpointResult | WorkspaceCheckpointLookupResult): boolean;
+/** Bind a fork result to the exact checkpoint request before using it. */
+export declare function workspaceForkResultMatchesRequest(request: WorkspaceForkRequest, result: WorkspaceForkResult | WorkspaceForkLookupResult): boolean;
+/** Bind cleanup confirmation to the exact provider resource and operation. */
+export declare function workspaceCleanupAcknowledgementMatches(request: WorkspaceCleanupRequest, acknowledgement: WorkspaceCleanupAcknowledgement): boolean;