@tangle-network/agent-interface 1.0.1 → 1.1.0

package/README.md

@@ -1,10 +1,34 @@
 # @tangle-network/agent-interface
 
-Shared TypeScript types and zod schemas that define the contract between Tangle
+Shared TypeScript types and Zod schemas that define the contract between Tangle
 agents, the sidecar, and provider adapters: capabilities, agent profiles,
 message parts, and harness descriptors. This is the canonical home for those
 shapes; higher-level packages import from here rather than redefining them.
 
+## Agent instances
+
+`AgentProfile` describes behavior. `AgentInstanceSpec` describes one optional managed Agent inside an existing execution environment. The environment remains the computer and security boundary, so it may host zero, one, or many Agent instances.
+
+```ts
+import type { AgentInstanceSpec } from "@tangle-network/agent-interface/agent-instance";
+
+const planner = {
+  id: "planner",
+  profile: {
+    name: "planner",
+    harness: "opencode",
+    prompt: { systemPrompt: "Plan before editing." },
+  },
+  workspace: { mode: "shared" },
+} satisfies AgentInstanceSpec;
+```
+
+The portable contract owns only inline profile and harness selection, shared or isolated workspace intent, public lifecycle state, a provider-sanitized failure summary, and idempotent stop shapes. Credentials, HTTP routes, process identifiers, placement, billing, snapshots, local resource controls, grants, and fencing remain provider-private.
+
+`shared` means ordinary same-computer file visibility. It is not automatic merge behavior or tenant isolation. `isolated` asks the provider for a private writable view and explicit inspect or commit behavior. Providers must reject unsatisfied machine requirements rather than silently replacing or migrating a live environment.
+
+The public `AgentInstanceRecord` contains a credential-free profile identity, not the full profile or provider request. Existing session APIs can implement this contract without a new service: one instance maps to one managed session, compatible sessions may reuse a backend process, and stop maps to idempotent session deletion or process release.
+
 ## Durable runs, interactions, and context
 
 `AgentRunControlRef` identifies a retained run without depending on a live JavaScript object and may carry the provider's admission digest so reconstruction can reject changed-input reuse.
@@ -66,8 +90,6 @@ Omitting `interactions` and `nativeContinuation`, or leaving the three durable b
 `replace` means the provider deletes the harness's own system prompt and installs `prompt.systemPrompt`; `append` means it keeps that prompt and adds `prompt.appendSystemPrompt` to it.
 A provider that can only append must declare `replace: false` and refuse a profile carrying `systemPrompt`, because quietly appending a requested replacement leaves the instructions the caller asked to delete in force.
 
-
-
 ## Install
 
 ```bash

package/dist/agent-instance.d.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import type { Sha256Digest } from "./agent-candidate.js";
+import type { AgentProfile } from "./agent-profile.js";
+import type { HarnessType } from "./harness.js";
+/** Lifecycle state of one managed Agent inside an execution environment. */
+export declare const AGENT_INSTANCE_STATUSES: readonly ["starting", "ready", "busy", "failed", "stopped"];
+export type AgentInstanceStatus = (typeof AGENT_INSTANCE_STATUSES)[number];
+/**
+ * How one Agent sees the provider-owned workspace.
+ *
+ * `shared` is ordinary same-computer visibility. `isolated` requests a private
+ * writable view with provider-defined inspect or commit behavior. Neither mode
+ * is a security boundary between mutually untrusted Agents.
+ */
+export declare const AGENT_INSTANCE_WORKSPACE_MODES: readonly ["shared", "isolated"];
+export type AgentInstanceWorkspaceMode = (typeof AGENT_INSTANCE_WORKSPACE_MODES)[number];
+export interface AgentInstanceWorkspace {
+    mode: AgentInstanceWorkspaceMode;
+}
+/**
+ * Provider-neutral request to start one managed Agent inside an existing
+ * execution environment.
+ *
+ * Omitting `profile` asks the provider for its default Agent configuration.
+ * Omitting `workspace` selects the provider's documented default. A profile
+ * never implies another VM.
+ */
+export interface AgentInstanceSpec {
+    /** Stable caller-selected id or idempotency key, when supported. */
+    id?: string;
+    /** Human-readable label; not immutable identity. */
+    name?: string;
+    /** Exact portable profile for this Agent. */
+    profile?: AgentProfile;
+    /** Optional execution override; otherwise the profile or provider decides. */
+    harness?: HarnessType;
+    workspace?: AgentInstanceWorkspace;
+}
+/** Credential-free identity of the profile bound to an Agent instance. */
+export interface AgentInstanceProfileIdentity {
+    name?: string;
+    digest: Sha256Digest;
+}
+/**
+ * Public failure summary. Providers must remove credentials and private
+ * implementation details before publishing this value.
+ */
+export interface AgentInstanceFailure {
+    code?: string;
+    message: string;
+}
+/**
+ * Portable snapshot of one managed Agent.
+ *
+ * The record deliberately excludes the full profile, provider request,
+ * credentials, grants, process ids, placement, and fencing state.
+ */
+export interface AgentInstanceRecord {
+    kind: "agent-instance";
+    schemaVersion: 1;
+    id: string;
+    name?: string;
+    profile?: AgentInstanceProfileIdentity;
+    /** Effective harness after profile and caller override resolution. */
+    harness?: HarnessType;
+    workspace: AgentInstanceWorkspace;
+    status: AgentInstanceStatus;
+    failure?: AgentInstanceFailure;
+    createdAtMs: number;
+    updatedAtMs: number;
+}
+export interface AgentInstanceStopRequest {
+    agentId: string;
+    /** Provider-defined hard termination after graceful stop cannot complete. */
+    force?: boolean;
+}
+export interface AgentInstanceStopAcknowledgement {
+    agentId: string;
+    outcome: "stopped" | "already-stopped" | "not-found";
+}
+export declare const agentInstanceStatusSchema: z.ZodEnum<{
+    failed: "failed";
+    starting: "starting";
+    ready: "ready";
+    busy: "busy";
+    stopped: "stopped";
+}>;
+export declare const agentInstanceWorkspaceModeSchema: z.ZodEnum<{
+    isolated: "isolated";
+    shared: "shared";
+}>;
+export declare const agentInstanceWorkspaceSchema: z.ZodType<AgentInstanceWorkspace>;
+export declare const agentInstanceSpecSchema: z.ZodType<AgentInstanceSpec>;
+export declare const agentInstanceProfileIdentitySchema: z.ZodType<AgentInstanceProfileIdentity>;
+export declare const agentInstanceFailureSchema: z.ZodType<AgentInstanceFailure>;
+export declare const agentInstanceRecordSchema: z.ZodType<AgentInstanceRecord>;
+export declare const agentInstanceStopRequestSchema: z.ZodType<AgentInstanceStopRequest>;
+export declare const agentInstanceStopAcknowledgementSchema: z.ZodType<AgentInstanceStopAcknowledgement>;

package/dist/agent-instance.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { isWellFormedUnicode, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+import { harnessTypeSchema } from "./harness.js";
+import { agentProfileSchema } from "./profile-schema.js";
+/** Lifecycle state of one managed Agent inside an execution environment. */
+export const AGENT_INSTANCE_STATUSES = [
+    "starting",
+    "ready",
+    "busy",
+    "failed",
+    "stopped",
+];
+/**
+ * How one Agent sees the provider-owned workspace.
+ *
+ * `shared` is ordinary same-computer visibility. `isolated` requests a private
+ * writable view with provider-defined inspect or commit behavior. Neither mode
+ * is a security boundary between mutually untrusted Agents.
+ */
+export const AGENT_INSTANCE_WORKSPACE_MODES = ["shared", "isolated"];
+const identifierSchema = z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z0-9](?:[A-Za-z0-9._:-]*[A-Za-z0-9])?$/, "identifier must use visible alphanumeric, '.', '_', ':', or '-' characters");
+const labelSchema = z
+    .string()
+    .min(1)
+    .max(256)
+    .refine((value) => isWellFormedUnicode(value) && !/[\u0000-\u001f\u007f]/u.test(value), "label must be valid Unicode without control characters");
+const failureMessageSchema = z
+    .string()
+    .min(1)
+    .max(16_384)
+    .refine((value) => isWellFormedUnicode(value) && !value.includes("\0"), "failure message must be valid Unicode without NUL");
+const timestampSchema = z
+    .number()
+    .int()
+    .nonnegative()
+    .max(Number.MAX_SAFE_INTEGER);
+export const agentInstanceStatusSchema = z.enum(AGENT_INSTANCE_STATUSES);
+export const agentInstanceWorkspaceModeSchema = z.enum(AGENT_INSTANCE_WORKSPACE_MODES);
+export const agentInstanceWorkspaceSchema = z.strictObject({
+    mode: agentInstanceWorkspaceModeSchema,
+});
+export const agentInstanceSpecSchema = z.strictObject({
+    id: identifierSchema.optional(),
+    name: labelSchema.optional(),
+    profile: agentProfileSchema.optional(),
+    harness: harnessTypeSchema.optional(),
+    workspace: agentInstanceWorkspaceSchema.optional(),
+});
+export const agentInstanceProfileIdentitySchema = z.strictObject({
+    name: labelSchema.optional(),
+    digest: sha256DigestSchema,
+});
+export const agentInstanceFailureSchema = z.strictObject({
+    code: identifierSchema.optional(),
+    message: failureMessageSchema,
+});
+export const agentInstanceRecordSchema = z
+    .strictObject({
+    kind: z.literal("agent-instance"),
+    schemaVersion: z.literal(1),
+    id: identifierSchema,
+    name: labelSchema.optional(),
+    profile: agentInstanceProfileIdentitySchema.optional(),
+    harness: harnessTypeSchema.optional(),
+    workspace: agentInstanceWorkspaceSchema,
+    status: agentInstanceStatusSchema,
+    failure: agentInstanceFailureSchema.optional(),
+    createdAtMs: timestampSchema,
+    updatedAtMs: timestampSchema,
+})
+    .superRefine((record, context) => {
+    if (record.updatedAtMs < record.createdAtMs) {
+        context.addIssue({
+            code: "custom",
+            path: ["updatedAtMs"],
+            message: "agent instance update cannot precede creation",
+        });
+    }
+    if (record.status === "failed" && record.failure === undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["failure"],
+            message: "failed agent instance requires a failure reason",
+        });
+    }
+    if (record.status !== "failed" && record.failure !== undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["failure"],
+            message: "failure reason is valid only for failed agent instances",
+        });
+    }
+});
+export const agentInstanceStopRequestSchema = z.strictObject({
+    agentId: identifierSchema,
+    force: z.boolean().optional(),
+});
+export const agentInstanceStopAcknowledgementSchema = z.strictObject({
+    agentId: identifierSchema,
+    outcome: z.enum(["stopped", "already-stopped", "not-found"]),
+});

package/dist/environment-interactive.d.ts

@@ -1050,8 +1050,8 @@ export declare const AgentInteractiveSessionStatusSchema: z.ZodDiscriminatedUnio
     }, z.core.$strict>;
     endedAt: z.ZodISODateTime;
     reason: z.ZodEnum<{
-        exited: "exited";
         stopped: "stopped";
+        exited: "exited";
         lost: "lost";
     }>;
     exitCode: z.ZodOptional<z.ZodNumber>;
@@ -1541,8 +1541,8 @@ export declare const AgentInteractiveSessionStopAcknowledgementSchema: z.ZodObje
     }>;
     effect: z.ZodEnum<{
         unknown: "unknown";
-        not_live: "not_live";
         stopped: "stopped";
+        not_live: "not_live";
         stop_requested: "stop_requested";
     }>;
     message: z.ZodOptional<z.ZodString>;

package/dist/environment-observation.d.ts

@@ -105,9 +105,9 @@ export declare const AgentEnvironmentStatusSchema: z.ZodEnum<{
     unknown: "unknown";
     failed: "failed";
     expired: "expired";
+    stopped: "stopped";
     pending: "pending";
     running: "running";
-    stopped: "stopped";
     provisioning: "provisioning";
 }>;
 /** Lifecycle, cleanup, continuity, and persistence of one environment. */
@@ -116,9 +116,9 @@ export declare const EnvironmentLifecycleSchema: z.ZodObject<{
         unknown: "unknown";
         failed: "failed";
         expired: "expired";
+        stopped: "stopped";
         pending: "pending";
         running: "running";
-        stopped: "stopped";
         provisioning: "provisioning";
     }>;
     cleanup: z.ZodOptional<z.ZodObject<{
@@ -441,9 +441,9 @@ export declare const AgentEnvironmentObservationSchema: z.ZodObject<{
                 unknown: "unknown";
                 failed: "failed";
                 expired: "expired";
+                stopped: "stopped";
                 pending: "pending";
                 running: "running";
-                stopped: "stopped";
                 provisioning: "provisioning";
             }>;
             cleanup: z.ZodOptional<z.ZodObject<{
@@ -489,9 +489,9 @@ export declare const AgentEnvironmentObservationSchema: z.ZodObject<{
                 unknown: "unknown";
                 failed: "failed";
                 expired: "expired";
+                stopped: "stopped";
                 pending: "pending";
                 running: "running";
-                stopped: "stopped";
                 provisioning: "provisioning";
             }>;
             cleanup: z.ZodOptional<z.ZodObject<{

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export * from "./agent-profile-improvement.js";
 export * from "./agent-profile-improvement-schema.js";
 export * from "./agent-execution-limits.js";
 export * from "./agent-profile.js";
+export * from "./agent-instance.js";
 export * from "./agent-profile-snapshot.js";
 export * from "./agent-profile-activation.js";
 export * from "./agent-profile-materialization.js";

package/dist/index.js

@@ -24,6 +24,7 @@ export * from "./agent-profile-improvement.js";
 export * from "./agent-profile-improvement-schema.js";
 export * from "./agent-execution-limits.js";
 export * from "./agent-profile.js";
+export * from "./agent-instance.js";
 export * from "./agent-profile-snapshot.js";
 export * from "./agent-profile-activation.js";
 export * from "./agent-profile-materialization.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -22,6 +22,11 @@
       "types": "./dist/agent-profile.d.ts",
       "default": "./dist/agent-profile.js"
     },
+    "./agent-instance": {
+      "import": "./dist/agent-instance.js",
+      "types": "./dist/agent-instance.d.ts",
+      "default": "./dist/agent-instance.js"
+    },
     "./profile-snapshot": {
       "import": "./dist/agent-profile-snapshot.js",
       "types": "./dist/agent-profile-snapshot.d.ts",