@tangle-network/agent-interface 0.47.0 → 0.49.0

package/dist/environment-terminal.js

@@ -0,0 +1,162 @@
+import { z } from "zod";
+import { boundedIdentifierSchema, boundedStringSchema } from "./contract-limits.js";
+const TERMINAL_MAX_DIMENSION = 10_000;
+const terminalDimensionSchema = z.number().int().positive().max(TERMINAL_MAX_DIMENSION);
+/**
+ * Provider-neutral handle for one interactive terminal.
+ *
+ * The handle carries no raw process id and no environment map, so a terminal
+ * reference never leaks host process detail or injected secrets. Every terminal
+ * is bound to a parent execution and carries an explicit expiry, so an orphan
+ * or an expired terminal fails closed at the call sites that read it.
+ */
+export const TerminalSessionRefSchema = z.strictObject({
+    terminalSessionId: boundedIdentifierSchema,
+    parentExecutionId: boundedIdentifierSchema,
+    name: boundedIdentifierSchema,
+    shell: boundedStringSchema.min(1),
+    command: boundedStringSchema.optional(),
+    cwd: boundedStringSchema.min(1),
+    cols: terminalDimensionSchema,
+    rows: terminalDimensionSchema,
+    connectionId: boundedIdentifierSchema.optional(),
+    createdAt: z.iso.datetime().max(64),
+    lastActivityAt: z.iso.datetime().max(64),
+    expiresAt: z.iso.datetime().max(64),
+    isRunning: z.boolean(),
+    exitCode: z.number().int().optional(),
+    exitSignal: boundedIdentifierSchema.optional(),
+    attachCount: z.number().int().nonnegative(),
+});
+/** Raw bytes written to the terminal, normalized to UTF-8 text. */
+export const TerminalInputSchema = z.strictObject({
+    data: boundedStringSchema,
+});
+/** New terminal geometry. */
+export const TerminalResizeSchema = z.strictObject({
+    cols: terminalDimensionSchema,
+    rows: terminalDimensionSchema,
+});
+/**
+ * Create-or-reattach request. A present `terminalSessionId` reattaches to an
+ * existing terminal; its absence opens a new one under the parent execution.
+ * `mode` selects an `attach` to a live process or a `logical` resume that
+ * replays retained output.
+ */
+export const TerminalAttachRequestSchema = z.strictObject({
+    parentExecutionId: boundedIdentifierSchema,
+    terminalSessionId: boundedIdentifierSchema.optional(),
+    connectionId: boundedIdentifierSchema.optional(),
+    mode: z.enum(["attach", "logical"]),
+    cols: terminalDimensionSchema.optional(),
+    rows: terminalDimensionSchema.optional(),
+    command: boundedStringSchema.optional(),
+    cwd: boundedStringSchema.optional(),
+});
+/** Result of a create-or-reattach request. */
+export const TerminalAttachResultSchema = z.discriminatedUnion("status", [
+    z.strictObject({
+        status: z.enum(["attached", "reattached"]),
+        mode: z.enum(["attach", "logical"]),
+        ref: TerminalSessionRefSchema,
+        attachCount: z.number().int().nonnegative(),
+    }),
+    z.strictObject({
+        status: z.literal("unavailable"),
+        reason: boundedStringSchema.min(1),
+    }),
+    z.strictObject({
+        status: z.literal("unknown"),
+        message: boundedStringSchema.min(1),
+        retryable: z.boolean(),
+    }),
+]);
+/**
+ * One ordered terminal output frame. `output` frames carry a monotonic `seq`
+ * that a consumer replays from, so a reconnect resumes without loss or
+ * duplication.
+ */
+export const TerminalOutputEventSchema = z.discriminatedUnion("type", [
+    z.strictObject({
+        type: z.literal("ready"),
+        cols: terminalDimensionSchema.optional(),
+        rows: terminalDimensionSchema.optional(),
+    }),
+    z.strictObject({
+        type: z.literal("output"),
+        seq: z.number().int().nonnegative(),
+        data: boundedStringSchema,
+    }),
+    z.strictObject({
+        type: z.literal("resize"),
+        cols: terminalDimensionSchema,
+        rows: terminalDimensionSchema,
+    }),
+    z.strictObject({
+        type: z.literal("exit"),
+        exitCode: z.number().int().optional(),
+        exitSignal: boundedIdentifierSchema.optional(),
+    }),
+    z.strictObject({
+        type: z.literal("error"),
+        message: boundedStringSchema.min(1),
+    }),
+]);
+/** Acknowledgement of a detach or close. */
+export const TerminalDetachAckSchema = z.discriminatedUnion("status", [
+    z.strictObject({
+        status: z.literal("detached"),
+        terminalSessionId: boundedIdentifierSchema,
+        connectionId: boundedIdentifierSchema.optional(),
+    }),
+    z.strictObject({
+        status: z.literal("closed"),
+        terminalSessionId: boundedIdentifierSchema,
+        exitCode: z.number().int().optional(),
+        exitSignal: boundedIdentifierSchema.optional(),
+    }),
+    z.strictObject({
+        status: z.literal("unknown"),
+        terminalSessionId: boundedIdentifierSchema,
+        message: boundedStringSchema.min(1),
+        retryable: z.boolean(),
+    }),
+]);
+/**
+ * Fail-closed usability check for a terminal reference. Returns true only when
+ * the reference parses, is running, and its expiry is in the future. A parse
+ * failure, a stopped terminal, or a past expiry denies use.
+ */
+export function terminalSessionUsable(ref, nowIso) {
+    const parsed = TerminalSessionRefSchema.safeParse(ref);
+    if (!parsed.success)
+        return false;
+    const now = Date.parse(nowIso);
+    const expiresAt = Date.parse(parsed.data.expiresAt);
+    if (!Number.isFinite(now) || !Number.isFinite(expiresAt))
+        return false;
+    if (now >= expiresAt)
+        return false;
+    return parsed.data.isRunning;
+}
+/** Bind an attach result to the parent execution and terminal it targeted. */
+export function terminalAttachResultMatchesRequest(request, result) {
+    const parsedRequest = TerminalAttachRequestSchema.safeParse(request);
+    const parsedResult = TerminalAttachResultSchema.safeParse(result);
+    if (!parsedRequest.success || !parsedResult.success)
+        return false;
+    const outcome = parsedResult.data;
+    if (outcome.status !== "attached" && outcome.status !== "reattached") {
+        return false;
+    }
+    if (outcome.mode !== parsedRequest.data.mode)
+        return false;
+    if (outcome.ref.parentExecutionId !== parsedRequest.data.parentExecutionId) {
+        return false;
+    }
+    if (parsedRequest.data.terminalSessionId !== undefined &&
+        outcome.ref.terminalSessionId !== parsedRequest.data.terminalSessionId) {
+        return false;
+    }
+    return true;
+}

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export * from "./host-services.js";
 export * from "./mcp.js";
 export * from "./provider-adapter.js";
 export type * from "./environment-provider.js";
-export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentNativeContextContinuationResultMatchesRequest, } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
 export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";

package/dist/index.js

@@ -7,7 +7,7 @@ export * from "./provider-config.js";
 export * from "./host-services.js";
 export * from "./mcp.js";
 export * from "./provider-adapter.js";
-export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentNativeContextContinuationResultMatchesRequest, } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
 export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";

package/dist/interaction-data.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { boundedIdentifierSchema, boundedStringSchema, CONTRACT_MAX_ARRAY_LENGTH, CONTRACT_MAX_MAP_ENTRIES, } from "./contract-limits.js";
-import { InteractionFieldNameSchema } from "./interaction-fields.js";
+import { InteractionFieldNameSchema, RESERVED_INTERACTION_FIELD_NAMES, } from "./interaction-fields.js";
 export const InteractionSecretReferenceSchema = z.strictObject({
     kind: z.literal("secret_handle"),
     handleId: boundedIdentifierSchema,
@@ -15,6 +15,25 @@ const InteractionDataValueSchema = z.union([
 ]);
 /** Field values keyed by InteractionField.name. */
 export const InteractionDataSchema = z
+    .unknown()
+    // A record parser assigns keys onto an ordinary object, so a raw own key
+    // `__proto__` invokes the legacy prototype setter and vanishes before any
+    // key schema runs. Reject reserved keys on the raw input, so this schema and
+    // `validateInteractionResponse` refuse the same value rather than one of them
+    // accepting a silently emptied object.
+    .superRefine((value, refinement) => {
+    if (value === null || typeof value !== "object")
+        return;
+    for (const key of Object.getOwnPropertyNames(value)) {
+        if (RESERVED_INTERACTION_FIELD_NAMES.has(key)) {
+            refinement.addIssue({
+                code: "custom",
+                message: `interaction field name "${key}" is reserved`,
+            });
+        }
+    }
+})
+    .pipe(z
     .record(InteractionFieldNameSchema, InteractionDataValueSchema)
     .superRefine((data, refinement) => {
     if (Object.keys(data).length > CONTRACT_MAX_MAP_ENTRIES) {
@@ -23,7 +42,7 @@ export const InteractionDataSchema = z
             message: "interaction data has too many fields",
         });
     }
-})
+}))
     .transform((data) => {
     const safe = Object.create(null);
     for (const key of Object.keys(data))

package/dist/interaction-fields.d.ts

@@ -1,4 +1,11 @@
 import { z } from "zod";
+/**
+ * Field names whose own-key form collides with object internals. A record
+ * parser drops a raw `__proto__` key through the legacy prototype setter before
+ * a key schema runs, so every schema and validator over interaction data
+ * rejects these names against one owner rather than a private copy.
+ */
+export declare const RESERVED_INTERACTION_FIELD_NAMES: ReadonlySet<string>;
 export declare const InteractionFieldNameSchema: z.ZodString;
 export declare const InteractionFieldSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"text">;

package/dist/interaction-fields.js

@@ -1,7 +1,17 @@
 import { z } from "zod";
 import { boundedIdentifierSchema, boundedStringSchema, CONTRACT_MAX_ARRAY_LENGTH, CONTRACT_MAX_STRING_LENGTH, } from "./contract-limits.js";
-const forbiddenFieldNames = new Set(["__proto__", "constructor", "prototype"]);
-export const InteractionFieldNameSchema = boundedIdentifierSchema.refine((value) => !forbiddenFieldNames.has(value), "interaction field name is reserved");
+/**
+ * Field names whose own-key form collides with object internals. A record
+ * parser drops a raw `__proto__` key through the legacy prototype setter before
+ * a key schema runs, so every schema and validator over interaction data
+ * rejects these names against one owner rather than a private copy.
+ */
+export const RESERVED_INTERACTION_FIELD_NAMES = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+export const InteractionFieldNameSchema = boundedIdentifierSchema.refine((value) => !RESERVED_INTERACTION_FIELD_NAMES.has(value), "interaction field name is reserved");
 // =============================================================================
 // Answer specification — describes the shape of a valid answer.
 // =============================================================================

package/dist/interaction-response-validation.js

@@ -1,6 +1,6 @@
 import { InteractionRequestSchema, InteractionResponseCommandSchema, InteractionResponseSchema, } from "./interaction-envelope.js";
+import { RESERVED_INTERACTION_FIELD_NAMES } from "./interaction-fields.js";
 import { validateResolutionForRequest } from "./interaction-resolution-validation.js";
-const FORBIDDEN_DATA_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 function validResponse(response) {
     const result = { ok: true };
     Object.defineProperty(result, "response", {
@@ -17,7 +17,7 @@ function forbiddenKeyErrors(response) {
     if (!data || typeof data !== "object")
         return [];
     return Object.getOwnPropertyNames(data)
-        .filter((key) => FORBIDDEN_DATA_KEYS.has(key))
+        .filter((key) => RESERVED_INTERACTION_FIELD_NAMES.has(key))
         .map((key) => `unknown field "${key}"`);
 }
 /** Validate one response against the exact outstanding request. */

package/dist/profile-schema.d.ts

@@ -120,6 +120,34 @@ export declare const reasoningEffortSchema: z.ZodEnum<{
     xhigh: "xhigh";
     ultracode: "ultracode";
 }>;
+/**
+ * Enforce the token ceilings that live together: each single ceiling must not
+ * exceed the total. It fails loud on a violation and never clamps a value.
+ * `reasoningEffort` is a separate quality dial and is not a bound here.
+ */
+export declare function enforceModelTokenBounds(hints: {
+    maxVisibleOutputTokens?: number;
+    maxReasoningTokens?: number;
+    maxTotalOutputTokens?: number;
+}, context: z.RefinementCtx): void;
+export declare const agentProfileModelHintsBaseSchema: 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>;
 export declare const agentProfileModelHintsSchema: z.ZodObject<{
     default: z.ZodOptional<z.ZodString>;
     small: z.ZodOptional<z.ZodString>;
@@ -133,6 +161,9 @@ export declare const agentProfileModelHintsSchema: z.ZodObject<{
         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>;
 /**
@@ -321,6 +352,9 @@ export declare const agentProfileSchema: z.ZodObject<{
             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<{

package/dist/profile-schema.js

@@ -91,13 +91,45 @@ export const agentProfileResourcesSchema = z.strictObject({
     failOnError: z.boolean().optional(),
 });
 export const reasoningEffortSchema = z.enum(REASONING_EFFORTS);
-export const agentProfileModelHintsSchema = z.strictObject({
+/**
+ * Enforce the token ceilings that live together: each single ceiling must not
+ * exceed the total. It fails loud on a violation and never clamps a value.
+ * `reasoningEffort` is a separate quality dial and is not a bound here.
+ */
+export function enforceModelTokenBounds(hints, context) {
+    const { maxVisibleOutputTokens, maxReasoningTokens, maxTotalOutputTokens } = hints;
+    if (maxTotalOutputTokens === undefined)
+        return;
+    if (maxVisibleOutputTokens !== undefined &&
+        maxVisibleOutputTokens > maxTotalOutputTokens) {
+        context.addIssue({
+            code: "custom",
+            path: ["maxVisibleOutputTokens"],
+            message: "maxVisibleOutputTokens must not exceed maxTotalOutputTokens",
+        });
+    }
+    if (maxReasoningTokens !== undefined &&
+        maxReasoningTokens > maxTotalOutputTokens) {
+        context.addIssue({
+            code: "custom",
+            path: ["maxReasoningTokens"],
+            message: "maxReasoningTokens must not exceed maxTotalOutputTokens",
+        });
+    }
+}
+// Base shape without cross-field checks, so candidate derivations may still
+// call `.omit`/`.extend`; zod refuses those on a schema that carries a refinement.
+export const agentProfileModelHintsBaseSchema = z.strictObject({
     default: z.string().optional(),
     small: z.string().optional(),
     provider: z.string().optional(),
     reasoningEffort: reasoningEffortSchema.optional(),
+    maxVisibleOutputTokens: z.number().int().positive().optional(),
+    maxReasoningTokens: z.number().int().positive().optional(),
+    maxTotalOutputTokens: z.number().int().positive().optional(),
     metadata: ownPropertyRecordSchema(z.unknown()).optional(),
 });
+export const agentProfileModelHintsSchema = agentProfileModelHintsBaseSchema.superRefine(enforceModelTokenBounds);
 /**
  * Replacement and addition are separate, independently optional fields, and the
  * pair is admitted on purpose: the effective prompt is `systemPrompt` followed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -16,6 +16,41 @@
       "import": "./dist/environment-provider.js",
       "types": "./dist/environment-provider.d.ts",
       "default": "./dist/environment-provider.js"
+    },
+    "./profile": {
+      "import": "./dist/agent-profile.js",
+      "types": "./dist/agent-profile.d.ts",
+      "default": "./dist/agent-profile.js"
+    },
+    "./profile-snapshot": {
+      "import": "./dist/agent-profile-snapshot.js",
+      "types": "./dist/agent-profile-snapshot.d.ts",
+      "default": "./dist/agent-profile-snapshot.js"
+    },
+    "./profile-schema": {
+      "import": "./dist/profile-schema.js",
+      "types": "./dist/profile-schema.d.ts",
+      "default": "./dist/profile-schema.js"
+    },
+    "./profile-security": {
+      "import": "./dist/profile-security.js",
+      "types": "./dist/profile-security.d.ts",
+      "default": "./dist/profile-security.js"
+    },
+    "./harness": {
+      "import": "./dist/harness.js",
+      "types": "./dist/harness.d.ts",
+      "default": "./dist/harness.js"
+    },
+    "./harness-capabilities": {
+      "import": "./dist/harness-capabilities.js",
+      "types": "./dist/harness-capabilities.d.ts",
+      "default": "./dist/harness-capabilities.js"
+    },
+    "./interaction": {
+      "import": "./dist/interaction.js",
+      "types": "./dist/interaction.d.ts",
+      "default": "./dist/interaction.js"
     }
   },
   "repository": {