@tangle-network/agent-interface 0.13.0 → 0.15.0

package/README.md

@@ -16,7 +16,13 @@ pnpm add @tangle-network/agent-interface
 ## Usage
 
 ```ts
-import type { BackendCapabilities, ProviderCapabilities } from "@tangle-network/agent-interface";
+import type {
+  AgentEnvironmentProvider,
+} from "@tangle-network/agent-interface/environment-provider";
+import type {
+  BackendCapabilities,
+  ProviderCapabilities,
+} from "@tangle-network/agent-interface";
 
 const caps: ProviderCapabilities = {
   supportsVision: true,
@@ -24,6 +30,36 @@ const caps: ProviderCapabilities = {
   supportsToolCalls: true,
   supportsComputerUse: false,
 };
+
+const provider: AgentEnvironmentProvider = {
+  name: "example",
+  capabilities: () => ({
+    profile: {
+      namedProfiles: false,
+      systemPrompt: true,
+      instructions: true,
+      tools: true,
+      permissions: true,
+      mcp: true,
+      subagents: false,
+      resources: { files: true, instructions: true, tools: true },
+      hooks: false,
+      modes: false,
+      runtimeUpdate: false,
+      validation: true,
+    },
+    streaming: { live: true, replay: false, detach: false, turnIdempotency: false },
+    sessions: { continue: false, list: false, messages: false },
+    workspace: { read: true, write: true, exec: true, git: false, upload: false, download: false },
+    branching: { checkpoint: false, fork: false },
+    placement: false,
+    usage: true,
+    confidential: false,
+  }),
+  create: async () => {
+    throw new Error("implement provider create()");
+  },
+};
 ```
 
 ## License

package/dist/environment-provider.d.ts

@@ -0,0 +1,190 @@
+import type { AgentProfile, AgentProfileCapabilities, AgentProfileValidationResult } from "./agent-profile.js";
+import type { InputPart, StreamEvent, TokenUsage } from "./index.js";
+/** Portable profile reference: inline profile or provider catalog id. */
+export type AgentProfileRef = AgentProfile | string;
+export type AgentEnvironmentStatus = "pending" | "provisioning" | "running" | "stopped" | "failed" | "expired" | "unknown";
+export type AgentSessionStatus = AgentEnvironmentStatus | "completed" | "cancelled";
+export interface WorkspaceRequest {
+    /** Provider-specific environment/template id, for example "universal". */
+    environment?: string;
+    /** Container image or image alias when the provider supports image-backed workspaces. */
+    image?: string;
+    /** Repository to clone or mount before the agent runs. */
+    repoUrl?: string;
+    /** Git ref for {@link repoUrl}. */
+    gitRef?: string;
+    /** Initial working directory inside the environment. */
+    cwd?: string;
+    /** Opaque provider-native workspace fields. */
+    providerOptions?: Record<string, unknown>;
+}
+export interface ResourceRequest {
+    cpu?: number;
+    memoryMb?: number;
+    diskMb?: number;
+    gpu?: string;
+    providerOptions?: Record<string, unknown>;
+}
+export interface AgentEnvironmentQuery {
+    name?: string;
+    metadata?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
+}
+export interface AgentEnvironmentSummary {
+    id: string;
+    provider: string;
+    name?: string;
+    status?: AgentEnvironmentStatus;
+    metadata?: Record<string, unknown>;
+}
+export interface ExecRequest {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface CheckpointRequest {
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CheckpointRef {
+    id: string;
+    provider?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ForkRequest {
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface PlacementInfo {
+    kind: "local" | "sandbox" | "fleet" | "provider";
+    sandboxId?: string;
+    fleetId?: string;
+    machineId?: string;
+    region?: string;
+    providerMetadata?: Record<string, unknown>;
+}
+export interface AgentTurnInput {
+    prompt?: string;
+    parts?: InputPart[];
+    sessionId?: string;
+    model?: string;
+    timeoutMs?: number;
+    executionId?: string;
+    lastEventId?: string;
+    turnId?: string;
+    detach?: boolean;
+    context?: Record<string, unknown>;
+    signal?: AbortSignal;
+    providerOptions?: Record<string, unknown>;
+}
+export interface AgentTurnResult {
+    text: string;
+    success: boolean;
+    error?: string;
+    sessionId?: string;
+    usage?: TokenUsage;
+    metadata?: Record<string, unknown>;
+    events?: AgentEnvironmentEvent[];
+}
+export interface AgentSessionRef {
+    id: string;
+    provider?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentEnvironmentEvent {
+    type: string;
+    data: Record<string, unknown>;
+    id?: string;
+    normalized?: StreamEvent;
+    usage?: TokenUsage;
+    providerEvent?: unknown;
+}
+export interface AgentSession {
+    readonly id: string;
+    status(): Promise<AgentSessionStatus | null>;
+    events(options?: {
+        since?: string;
+        signal?: AbortSignal;
+    }): AsyncIterable<AgentEnvironmentEvent>;
+    result(): Promise<AgentTurnResult>;
+    prompt(input: AgentTurnInput): Promise<AgentTurnResult>;
+    cancel(): Promise<void>;
+}
+export interface AgentEnvironment {
+    readonly id: string;
+    readonly provider: string;
+    readonly name?: string;
+    status(): Promise<AgentEnvironmentStatus>;
+    stream(input: AgentTurnInput): AsyncIterable<AgentEnvironmentEvent>;
+    dispatch?(input: AgentTurnInput): Promise<AgentSessionRef>;
+    session?(id: string): AgentSession;
+    read?(path: string, options?: {
+        sessionId?: string;
+    }): Promise<string>;
+    write?(path: string, content: string, options?: {
+        sessionId?: string;
+    }): Promise<void>;
+    exec?(command: string, options?: ExecRequest): Promise<ExecResult>;
+    checkpoint?(options?: CheckpointRequest): Promise<CheckpointRef>;
+    fork?(checkpoint: CheckpointRef, options?: ForkRequest): Promise<AgentEnvironment>;
+    placement?(): Promise<PlacementInfo>;
+    refresh?(): Promise<void>;
+    destroy?(): Promise<void>;
+}
+export interface AgentEnvironmentCapabilities {
+    profile: AgentProfileCapabilities;
+    streaming: {
+        live: boolean;
+        replay: boolean;
+        detach: boolean;
+        turnIdempotency: boolean;
+    };
+    sessions: {
+        continue: boolean;
+        list: boolean;
+        messages: boolean;
+    };
+    workspace: {
+        read: boolean;
+        write: boolean;
+        exec: boolean;
+        git: boolean;
+        upload: boolean;
+        download: boolean;
+    };
+    branching: {
+        checkpoint: boolean;
+        fork: boolean;
+    };
+    placement: boolean;
+    usage: boolean;
+    confidential: boolean;
+}
+export interface CreateAgentEnvironmentInput {
+    profile: AgentProfileRef;
+    /** Agent backend inside the provider, for example "opencode" or "codex". */
+    backend?: string;
+    workspace?: WorkspaceRequest;
+    resources?: ResourceRequest;
+    env?: Record<string, string>;
+    secrets?: string[] | Record<string, string>;
+    metadata?: Record<string, unknown>;
+    name?: string;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+    providerOptions?: Record<string, unknown>;
+}
+export interface AgentEnvironmentProvider {
+    readonly name: string;
+    capabilities(): AgentEnvironmentCapabilities | Promise<AgentEnvironmentCapabilities>;
+    validateProfile?(profile: AgentProfileRef): AgentProfileValidationResult | Promise<AgentProfileValidationResult>;
+    create(input: CreateAgentEnvironmentInput): Promise<AgentEnvironment>;
+    get?(id: string): Promise<AgentEnvironment | null>;
+    list?(query?: AgentEnvironmentQuery): Promise<AgentEnvironmentSummary[]>;
+}

package/dist/environment-provider.js

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

package/dist/harness-capabilities.d.ts

@@ -29,6 +29,20 @@ export declare function harnessSupportsModel(harness: HarnessType, modelId: stri
 /** The harness to adopt for a model whose provider is vendor-locked (`anthropic` → `claude-code`,
  *  `openai` → `codex`, `moonshot` → `kimi-code`); `null` when any router-backed harness will do. */
 export declare function preferredHarnessForModel(modelId: string): HarnessType | null;
+/**
+ * Keep `modelId` when the harness can run it; otherwise return the harness's best compatible id from
+ * `candidateIds` (preferred patterns in order, highest version within a pattern). When nothing in the
+ * candidate list fits, the original id is returned unchanged so the caller sees the incompatibility
+ * instead of a silent wrong substitution. `candidateIds` are canonical ("provider/model") ids — the
+ * caller maps its own catalog shape down to ids, keeping this layer catalog-agnostic.
+ */
+export declare function snapModelToHarness(harness: HarnessType, modelId: string, candidateIds: readonly string[]): string;
+/**
+ * Keep the harness when it can run `modelId`; otherwise return the model's native harness
+ * (anthropic → claude-code, openai → codex, moonshot → kimi-code), falling back to the router-backed
+ * `opencode` for everything else.
+ */
+export declare function snapHarnessToModel(harness: HarnessType, modelId: string): HarnessType;
 /** The reasoning efforts a harness can express, independent of model — `none` up to its ceiling. */
 export declare function harnessReasoningEfforts(harness: HarnessType): readonly ReasoningEffort[];
 /** What the caller knows about a model's own reasoning capability (from a model catalog). */

package/dist/harness-capabilities.js

@@ -29,10 +29,13 @@ export const reasoningLadder = [
  * Provider prefixes a harness is vendor-locked to (canonical-id prefix, e.g. `anthropic`, `openai`).
  * A harness with no entry is router-backed: it runs any model. Keyed by the BASE runner — aliases
  * (`claude`/`claudish`/`kimi`) resolve through `canonicalizeHarness` first.
+ *
+ * `nanoclaw` is deliberately absent despite the "claw" name: its runner routes every provider through
+ * the Tangle router (canonical model id straight to the gateway), so it is router-backed like
+ * `opencode` — not Anthropic-locked.
  */
 const harnessProviderLock = {
     "claude-code": ["anthropic"],
-    nanoclaw: ["anthropic"],
     codex: ["openai"],
     "kimi-code": ["moonshot"],
 };
@@ -68,19 +71,69 @@ export function preferredHarnessForModel(modelId) {
     }
     return null;
 }
+// ── Harness ↔ model snapping (catalog-aware) ─────────────────────────────────
+/**
+ * Per-harness ranking patterns for {@link snapModelToHarness}, best first; within one pattern the
+ * highest version wins (numeric-aware). Only vendor-locked harnesses need an entry — a router-backed
+ * harness never snaps (it runs the model as-is). Keyed by the BASE runner (aliases canonicalized).
+ */
+const harnessPreferredModelPatterns = {
+    "claude-code": [
+        /^anthropic\/claude-opus-[\d.-]+$/,
+        /^anthropic\/claude-sonnet-[\d.-]+$/,
+        /^anthropic\//,
+    ],
+    codex: [/^openai\/gpt-\d+(\.\d+)?$/, /^openai\/gpt/, /^openai\//],
+    "kimi-code": [/^moonshot\//],
+};
+const numericDesc = new Intl.Collator(undefined, {
+    numeric: true,
+    sensitivity: "base",
+});
+/**
+ * Keep `modelId` when the harness can run it; otherwise return the harness's best compatible id from
+ * `candidateIds` (preferred patterns in order, highest version within a pattern). When nothing in the
+ * candidate list fits, the original id is returned unchanged so the caller sees the incompatibility
+ * instead of a silent wrong substitution. `candidateIds` are canonical ("provider/model") ids — the
+ * caller maps its own catalog shape down to ids, keeping this layer catalog-agnostic.
+ */
+export function snapModelToHarness(harness, modelId, candidateIds) {
+    if (harnessSupportsModel(harness, modelId))
+        return modelId;
+    const patterns = harnessPreferredModelPatterns[canonicalizeHarness(harness)] ?? [];
+    for (const pattern of patterns) {
+        const matches = candidateIds
+            .filter((id) => pattern.test(id))
+            .sort((a, b) => numericDesc.compare(b, a));
+        if (matches.length > 0)
+            return matches[0];
+    }
+    return candidateIds.find((id) => harnessSupportsModel(harness, id)) ?? modelId;
+}
+/**
+ * Keep the harness when it can run `modelId`; otherwise return the model's native harness
+ * (anthropic → claude-code, openai → codex, moonshot → kimi-code), falling back to the router-backed
+ * `opencode` for everything else.
+ */
+export function snapHarnessToModel(harness, modelId) {
+    if (harnessSupportsModel(harness, modelId))
+        return harness;
+    return preferredHarnessForModel(modelId) ?? "opencode";
+}
 // ── Reasoning-effort support ──────────────────────────────────────────────────
 /**
  * The highest reasoning effort a harness's runtime can express (its native clamp ceiling). Grounded
  * in cli-bridge: codex's `model_reasoning_effort` caps at `high` (xhigh/ultracode clamp down); kimi's
  * `--thinking` is binary, so `high` is its "on"; claude-code carries the full range; `cli-base` has
- * no agent and thus no thinking. Router/model-driven harnesses default to the full range.
+ * no agent and thus no thinking; `nanoclaw`'s runner sends no thinking flag, so it expresses only
+ * `none`. Router/model-driven harnesses default to the full range.
  */
 const harnessReasoningCeiling = {
     "cli-base": "none",
     codex: "high",
     "kimi-code": "high",
     "claude-code": "ultracode",
-    nanoclaw: "ultracode",
+    nanoclaw: "none",
 };
 /** The reasoning efforts a harness can express, independent of model — `none` up to its ceiling. */
 export function harnessReasoningEfforts(harness) {

package/dist/index.d.ts

@@ -5,6 +5,7 @@
  * This package defines the contract between the sidecar and provider implementations.
  */
 import type { InteractionRequest, InteractionResponse } from "./interaction.js";
+export type * from "./environment-provider.js";
 export type BackendCapabilities = {
     streaming: boolean;
     toolUse: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "type": "module",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -10,6 +10,11 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./environment-provider": {
+      "import": "./dist/environment-provider.js",
+      "types": "./dist/environment-provider.d.ts",
+      "default": "./dist/environment-provider.js"
     }
   },
   "repository": {
@@ -31,11 +36,14 @@
   },
   "devDependencies": {
     "@types/node": "25.6.0",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "check-types": "tsc --noEmit",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }