@tangle-network/agent-interface 0.45.0 → 0.46.0

package/dist/contract-limits.js

@@ -0,0 +1,175 @@
+import { z } from "zod";
+/** Limits applied before a value is hashed, copied, or sent to a provider. */
+export const CONTRACT_MAX_STRING_LENGTH = 16_384;
+export const CONTRACT_MAX_IDENTIFIER_LENGTH = 512;
+export const CONTRACT_MAX_ARRAY_LENGTH = 1_024;
+export const CONTRACT_MAX_MAP_ENTRIES = 256;
+export const CONTRACT_MAX_JSON_DEPTH = 16;
+export const CONTRACT_MAX_JSON_BYTES = 1_048_576;
+export const CONTRACT_MAX_JSON_NODES = 8_192;
+export const boundedStringSchema = z.string().max(CONTRACT_MAX_STRING_LENGTH);
+export const boundedIdentifierSchema = boundedStringSchema
+    .min(1)
+    .max(CONTRACT_MAX_IDENTIFIER_LENGTH)
+    .refine((value) => value.trim() === value, "identifier cannot have outer whitespace");
+/**
+ * Validate JSON without asking Zod to recursively copy an attacker-sized
+ * value. This is intentionally iterative so depth and collection limits are
+ * checked before canonical serialization.
+ */
+export function isBoundedJsonValue(value) {
+    const pending = [{ value, depth: 0 }];
+    const ancestors = new Set();
+    let nodes = 0;
+    while (pending.length > 0) {
+        const item = pending.pop();
+        if (!item)
+            continue;
+        nodes += 1;
+        if (nodes > CONTRACT_MAX_JSON_NODES)
+            return false;
+        const current = item.value;
+        if (item.leave) {
+            ancestors.delete(current);
+            continue;
+        }
+        if (current === undefined)
+            return false;
+        if (current === null || typeof current === "boolean")
+            continue;
+        if (typeof current === "string") {
+            if (current.length > CONTRACT_MAX_STRING_LENGTH)
+                return false;
+            continue;
+        }
+        if (typeof current === "number") {
+            if (!Number.isFinite(current))
+                return false;
+            continue;
+        }
+        if (typeof current !== "object" || item.depth >= CONTRACT_MAX_JSON_DEPTH) {
+            return false;
+        }
+        if (ancestors.has(current))
+            return false;
+        ancestors.add(current);
+        pending.push({ value: current, depth: item.depth, leave: true });
+        if (Array.isArray(current)) {
+            if (current.length > CONTRACT_MAX_ARRAY_LENGTH)
+                return false;
+            for (const entry of current) {
+                pending.push({ value: entry, depth: item.depth + 1 });
+            }
+            continue;
+        }
+        const prototype = Object.getPrototypeOf(current);
+        if (prototype !== Object.prototype && prototype !== null)
+            return false;
+        const keys = Object.keys(current);
+        if (keys.length > CONTRACT_MAX_MAP_ENTRIES)
+            return false;
+        for (const key of keys) {
+            if (key.length > CONTRACT_MAX_IDENTIFIER_LENGTH)
+                return false;
+            pending.push({
+                value: current[key],
+                depth: item.depth + 1,
+            });
+        }
+    }
+    return true;
+}
+/** Validate digest input while matching JSON's omission of undefined object fields. */
+export function isBoundedJsonMaterial(value) {
+    const pending = [{ value, depth: 0 }];
+    const ancestors = new Set();
+    let nodes = 0;
+    while (pending.length > 0) {
+        const item = pending.pop();
+        if (!item)
+            continue;
+        if (item.leave) {
+            ancestors.delete(item.value);
+            continue;
+        }
+        if (item.value === undefined) {
+            if (item.omitUndefined === true)
+                continue;
+            return false;
+        }
+        nodes += 1;
+        if (nodes > CONTRACT_MAX_JSON_NODES)
+            return false;
+        const current = item.value;
+        if (current === null || typeof current === "boolean")
+            continue;
+        if (typeof current === "string") {
+            if (current.length > CONTRACT_MAX_STRING_LENGTH)
+                return false;
+            continue;
+        }
+        if (typeof current === "number") {
+            if (!Number.isFinite(current))
+                return false;
+            continue;
+        }
+        if (typeof current !== "object" || item.depth >= CONTRACT_MAX_JSON_DEPTH) {
+            return false;
+        }
+        if (ancestors.has(current))
+            return false;
+        ancestors.add(current);
+        pending.push({ value: current, depth: item.depth, leave: true });
+        if (Array.isArray(current)) {
+            if (current.length > CONTRACT_MAX_ARRAY_LENGTH)
+                return false;
+            for (const entry of current) {
+                pending.push({ value: entry, depth: item.depth + 1 });
+            }
+            continue;
+        }
+        const prototype = Object.getPrototypeOf(current);
+        if (prototype !== Object.prototype && prototype !== null)
+            return false;
+        const keys = Object.keys(current);
+        if (keys.length > CONTRACT_MAX_MAP_ENTRIES)
+            return false;
+        for (const key of keys) {
+            if (key.length > CONTRACT_MAX_IDENTIFIER_LENGTH)
+                return false;
+            pending.push({
+                value: current[key],
+                depth: item.depth + 1,
+                omitUndefined: true,
+            });
+        }
+    }
+    return true;
+}
+export const boundedJsonSchema = z.custom(isBoundedJsonValue, {
+    message: "value exceeds the contract bounds or is not finite JSON",
+});
+export const boundedJsonRecordSchema = z.custom((value) => typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    isBoundedJsonValue(value), { message: "metadata exceeds the contract bounds or is not a JSON object" });
+export function assertBoundedJson(value) {
+    if (!isBoundedJsonValue(value)) {
+        throw new Error("value exceeds the contract bounds or is not finite JSON");
+    }
+}
+export function assertBoundedSerializedJson(value) {
+    if (new TextEncoder().encode(value).byteLength > CONTRACT_MAX_JSON_BYTES) {
+        throw new Error("serialized contract material exceeds its byte bound");
+    }
+}
+/** Copy arbitrary metadata into a map that cannot inherit prototype keys. */
+export function nullPrototypeRecord(value) {
+    const result = Object.create(null);
+    for (const key of Object.keys(value))
+        result[key] = value[key];
+    return result;
+}
+export function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}

package/dist/environment-exact-process.d.ts

@@ -0,0 +1,161 @@
+import type { AgentCandidateTermination } from "./agent-candidate.js";
+export type AgentExactProcessEgressMode = "blocked" | "strict";
+/**
+ * Outbound network policy for an exact process environment. `blocked` denies
+ * every protocol. `strict` permits only the named domains; direct-address,
+ * alternate-protocol, and cross-environment bypasses must fail.
+ */
+export type AgentExactProcessEgressPolicy = {
+    mode: "blocked";
+} | {
+    mode: "strict";
+    allowDomains: readonly string[];
+};
+/** Explicit portable limits for an exact process environment. */
+export interface AgentExactProcessResources {
+    /** Positive CPU core count. */
+    cpu: number;
+    /** Positive integer mebibytes of memory. */
+    memoryMb: number;
+    /** Positive integer mebibytes of disk. */
+    diskMb: number;
+}
+/** Terminal or running state reported by an exact process host. */
+export interface AgentExactProcessStatus {
+    pid: number;
+    running: boolean;
+    /** -1 while running; the exact process exit code after termination. */
+    exitCode: number;
+    exitSignal?: string;
+    /** Required after termination; absent only while running. */
+    termination?: AgentCandidateTermination;
+}
+/** Recoverable handle for one shell-free process. */
+export interface AgentExactProcess {
+    readonly pid: number;
+    status(options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentExactProcessStatus>;
+    wait(options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentCandidateTermination>;
+    /** Force-stop the full process tree. Idempotent after the process exits. */
+    kill(options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Each iteration replays buffered UTF-8 stdout, then continues until exit. */
+    stdout(options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<string>;
+    /** Each iteration replays buffered UTF-8 stderr, then continues until exit. */
+    stderr(options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<string>;
+}
+/** Shell-free launch whose environment replaces, rather than extends, ambient variables. */
+export interface AgentExactProcessLaunch {
+    /** Absolute path unless {@link env} supplies an explicit `PATH`. */
+    executable: string;
+    args: readonly string[];
+    cwd: string;
+    env: Readonly<Record<string, string>>;
+    stdin?: string;
+    /** Positive integer milliseconds, or zero to disable the process timeout. */
+    timeoutMs: number;
+}
+export interface AgentExactProcessManager {
+    list(options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentExactProcessStatus[]>;
+    get(pid: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentExactProcess | null>;
+    /**
+     * The abort signal is checked before and after spawn dispatch.
+     * If abort is observed after a process starts, the provider kills its tree
+     * before rejecting the spawn operation.
+     */
+    spawn(input: AgentExactProcessLaunch, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentExactProcess>;
+}
+/**
+ * Fresh environment with no provider-managed user workload.
+ *
+ * Authenticated provider control services may exist, but no customer workload
+ * ingress or provider-managed user process may exist. The launched process
+ * sees only its supplied environment variables, with no ambient or injected
+ * secrets.
+ */
+export interface AgentExactProcessEnvironment {
+    readonly id: string;
+    readonly provider: string;
+    readonly metadata?: Record<string, unknown>;
+    readonly process: AgentExactProcessManager;
+    /**
+     * Write exact bytes to an absolute path with a POSIX mode from 0 through
+     * 07777.
+     *
+     * The abort signal is checked before and after the write.
+     * Once dispatched the write is not cancellable, so an abort may reject after
+     * the bytes have landed.
+     */
+    writeFile(path: string, bytes: Uint8Array, options: {
+        mode: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Read exact bytes, or fail before content is loaded when the file exceeds
+     * maxBytes. A file that grows after the size check is still rejected, but
+     * only after its content was transferred. Reads have no side effect, so the
+     * abort signal may reject at any point.
+     */
+    readFile(path: string, options: {
+        maxBytes: number;
+        signal?: AbortSignal;
+    }): Promise<Uint8Array>;
+    destroy(options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+export interface AgentExactProcessEnvironmentQuery {
+    /** Every supplied key/value must match persisted environment metadata exactly. */
+    metadata?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
+    /** Abort a paginated lookup before the next remote page or conversion. */
+    signal?: AbortSignal;
+}
+/** Input for a fresh environment with no provider-managed agent process. */
+export interface CreateAgentExactProcessEnvironmentInput {
+    /** Provider-specific immutable image reference. */
+    image: string;
+    egress: AgentExactProcessEgressPolicy;
+    /** Positive integer milliseconds. */
+    maxLifetimeMs: number;
+    /** Positive integer milliseconds when supplied. */
+    provisionTimeoutMs?: number;
+    /** Required limits; exact execution never inherits provider defaults. */
+    resources: AgentExactProcessResources;
+    metadata: Record<string, unknown>;
+    idempotencyKey: string;
+    signal?: AbortSignal;
+    /** Provider-native fields may narrow, but never weaken, the isolation contract. */
+    providerOptions?: Record<string, unknown>;
+}
+/** Optional all-or-nothing exact process capability of an environment provider. */
+export interface AgentExactProcessProvider {
+    /**
+     * Repeating the same idempotency key and input returns the same environment.
+     * Reusing the key with any different create input must fail.
+     * Unsupported egress modes must fail instead of weakening the policy.
+     */
+    create(input: CreateAgentExactProcessEnvironmentInput): Promise<AgentExactProcessEnvironment>;
+    /** Ordinary environments must return null. */
+    get(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentExactProcessEnvironment | null>;
+    /** Return every matching exact environment; providers own any native pagination. */
+    list(query?: AgentExactProcessEnvironmentQuery, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentExactProcessEnvironment[]>;
+}

package/dist/environment-exact-process.js

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

package/dist/environment-profile-capabilities.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+export declare const AgentProfileCapabilitiesSchema: z.ZodObject<{
+    namedProfiles: z.ZodBoolean;
+    systemPrompt: z.ZodObject<{
+        replace: z.ZodBoolean;
+        append: z.ZodBoolean;
+    }, z.core.$strict>;
+    instructions: z.ZodBoolean;
+    tools: z.ZodBoolean;
+    permissions: z.ZodBoolean;
+    mcp: z.ZodBoolean;
+    subagents: z.ZodBoolean;
+    resources: z.ZodObject<{
+        files: z.ZodBoolean;
+        instructions: z.ZodBoolean;
+        tools: z.ZodOptional<z.ZodBoolean>;
+        skills: z.ZodOptional<z.ZodBoolean>;
+        agents: z.ZodOptional<z.ZodBoolean>;
+        commands: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+    hooks: z.ZodOptional<z.ZodBoolean>;
+    modes: z.ZodOptional<z.ZodBoolean>;
+    runtimeUpdate: z.ZodBoolean;
+    validation: z.ZodBoolean;
+    extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;

package/dist/environment-profile-capabilities.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { boundedIdentifierSchema, CONTRACT_MAX_ARRAY_LENGTH, } from "./contract-limits.js";
+export const AgentProfileCapabilitiesSchema = z.strictObject({
+    namedProfiles: z.boolean(),
+    /*
+     * Replacement and addition are independent provider capabilities. Require
+     * both declarations so an omitted bit cannot be mistaken for support.
+     */
+    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(boundedIdentifierSchema)
+        .max(CONTRACT_MAX_ARRAY_LENGTH)
+        .optional(),
+});