@nylorun/harness 0.15.0-beta → 0.16.0-beta

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.16.0-beta
+
+### Minor Changes
+
+- 3a88f51: Ship Agent-Plugins (`plugin()` / `loadPlugin`), Skills (`load_skill` / skill resources), Runtime MCP pool + vault credentials, and manifest v3 capability fields. Validate completed tool `output` against the tool output schema so ordinary tools with `outputSchema` no longer false-fail as `tool.invalid-output`.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [3a88f51]
+  - @nylorun/core@0.2.0-beta
+
 ## 0.15.0-beta
 
 ### Major Changes

package/HOST_CONTRACT.md

@@ -1,18 +1,18 @@
 # Durable execution and session protocol — beta freeze
 
-Artifact: `@nylorun/harness@0.14.0-beta.3`. Package version is separate from protocol 1, definition schema 2, durable checkpoint 1 / engine `hosted-1`, and inner execution checkpoint 1. Public execution API and shared contracts are the compatibility boundary. Cloud installs published npm packages and does not import the OSS Runtime.
+Artifact: `@nylorun/harness@0.14.0-beta.3`. Package version is separate from protocol 1, definition schema 3, durable checkpoint 1 / engine `hosted-1`, and inner execution checkpoint 1. Public execution API and shared contracts are the compatibility boundary. Cloud installs published npm packages and does not import the OSS Runtime.
 
 ## HTTP (both hosts)
 
-Bearer application credentials: `PUT /v1/agents/:agentId` (`PutAgentRequest`: requestId, complete manifest, implementationVersion); `PUT /v1/sessions/:sessionId` (`PutSessionRequest`: requestId, agentId, trusted ownerUserId, optional info); `GET /v1/sessions/:sessionId`; `POST /v1/sessions/:sessionId/commands`; `GET /v1/sessions/:sessionId/items?cursor=...`; `GET /v1/sessions/:sessionId/events?cursor=...` (SSE, Last-Event-ID also accepted). Commands use `SessionCommandSchema`. Message input is `content`, not text. Runtime configuration selects models; saved definitions do not. Session creation pins manifest hash and implementation version. GET session returns id, agentId, ownerUserId, status, activeTurnId, plus inspectable waits/uncertainty as available. History returns `{items: LiveEvent[], cursor: string|null}`; empty history cursor is null.
+Bearer application credentials: `PUT /v1/agents/:agentId` (`PutAgentRequest`: requestId, complete manifest, implementationVersion, optional pluginRoots); `PUT /v1/sessions/:sessionId` (`PutSessionRequest`: requestId, agentId, trusted ownerUserId, optional info, optional vaultIds, optional credentialSelections); `GET /v1/sessions/:sessionId`; `POST /v1/sessions/:sessionId/commands`; `GET /v1/sessions/:sessionId/items?cursor=...`; `GET /v1/sessions/:sessionId/events?cursor=...` (SSE, Last-Event-ID also accepted); vault administration `POST/GET/DELETE /v1/vaults` and `/v1/vaults/:vaultId/credentials`. Commands use `SessionCommandSchema`. Vault creates and credential rotations use `idempotencyKey`; requestId is excluded from comparison; the same key and body replay the stored metadata response; a changed body is 409. Credential responses omit secret values. `GET /v1/vaults?ownerUserId=` lists that user's vaults. A session attaches only vaults with the same ownerUserId. A later session PUT may replace vaultIds and credentialSelections; agentId, ownerUserId, and info stay the creation identity. GET session returns id, agentId, ownerUserId, status, activeTurnId, vaultIds, credentialSelections, mcpSnapshot, mcpDiagnostics, plus inspectable waits/uncertainty as available. mcpSnapshot is null until the first turn discovers MCP tools; it is then pinned for the session and contains no secrets. pluginRoots are stored beside the agent definition and are not part of the manifest hash. History returns `{items: LiveEvent[], cursor: string|null}`; empty history cursor is null. Executor credentials cannot call vault routes.
 
-Separate scoped executor bearer credentials: `GET /v1/executors/connect` emits `event: work_available` / `data: {"type":"work_available"}` after connection and committed work; `GET /v1/actions` returns `{actions: Action[]}`; `POST /v1/actions/:actionId/claim` uses ActionClaimRequest; `POST /v1/actions/:actionId/heartbeat` uses ActionHeartbeatRequest and returns leaseExpiresAt. Claim returns ActionClaim. Action result is the `action_result` session command with executor authorization, never observer authorization. Claim identity is server-generated and generation monotonically increases. Credentials limit agentId, manifestHash, and implementationVersion; clients cannot broaden their scope. Subscribe before discovery; rediscover after reconnect; notifications never authorize execution.
+Separate scoped executor bearer credentials: `GET /v1/executors/connect` emits `event: work_available` / `data: {"type":"work_available"}` after connection and committed work; `GET /v1/actions` returns `{actions: Action[]}`; `POST /v1/actions/:actionId/claim` uses ActionClaimRequest; `POST /v1/actions/:actionId/heartbeat` uses ActionHeartbeatRequest and returns leaseExpiresAt. Claim returns ActionClaim. Action result is the `action_result` session command with executor authorization, never observer authorization. Claim identity is server-generated and generation monotonically increases. Credentials authorize an executor by agentId. A manifestHash stored on an existing token is ignored, and claim requests do not send one. In-flight actions for that agent stay claimable after the registered digest changes. Clients cannot broaden their agent scope. Subscribe before discovery; rediscover after reconnect; notifications never authorize execution.
 
 All command idempotency keys bind to canonical request content within a session; requestId is transport metadata and is excluded from content comparison; exact semantic duplicates return the stored original response; changed content conflicts (409). A completed action's matching claim/generation/outcome returns its original receipt even after expiry. Conflicting duplicates and any other stale/expired claim are rejected. Heartbeat cannot resurrect an expired claim. Expired in-flight customer work is uncertain, not automatically reoffered. Results after cancellation cannot resume a turn. Application observers cannot claim or submit action results. No hardcoded production credentials.
 
 ## Engine host
 
-`createDurableCheckpoint({manifest,sessionId,turnId,input,state?,info?,segment?})`, `runDurable({manifest,checkpoint,host,signal?})` from `/run`. `DurableHost.resolveEffect(HostEffect)` atomically creates or reads an individually identified effect and returns `{status:'completed',outcome:{value,statePatch?}}` or `{status:'pending'|'uncertain'}`. Model effect `input` is the complete ModelCall (instructions/history/tools/output schema); context contains a JSON projection of ModelRequest and invocationId. Its completed value is a ModelCandidate or string. Runtime provider code owns credentials and invocation. Tools/hooks have capabilityId, toolName for tools, serialized input and context. Tool result value is a ToolOutcome or a plain tool output; statePatch contains changed session keys. Before/after hook values are Patch/Decision. Tool context includes invocationId, resume, state, info and stable idempotencyKey. Customer implementationVersion is pinned by the runtime outside durable checkpoints.
+`createDurableCheckpoint({manifest,sessionId,turnId,input,state?,info?,segment?})`, `runDurable({manifest,checkpoint,host,signal?,sessionTools?})` from `/run`. `DurableHost.resolveEffect(HostEffect)` atomically creates or reads an individually identified effect and returns `{status:'completed',outcome:{value,statePatch?}}` or `{status:'pending'|'uncertain'}`. Model effect `input` is the complete ModelCall (instructions/history/tools/output schema); context contains a JSON projection of ModelRequest and invocationId. Its completed value is a ModelCandidate or string. Runtime provider code owns credentials and invocation. Tools/hooks have capabilityId, toolName for tools, serialized input and context. Tool result value is a ToolOutcome or a plain tool output; statePatch contains changed session keys. Before/after hook values are Patch/Decision. Tool context includes invocationId, resume, state, info and stable idempotencyKey. Customer implementationVersion is pinned by the runtime outside durable checkpoints.
 
 Persist checkpoint BEFORE scheduling, effect intent BEFORE provider invocation or notification, and outcome BEFORE resumption. Journaling an entire runDurable call as one replayable operation is forbidden. The durable path deterministically reconstructs a segment from its immutable starting checkpoint and individually cached effect outcomes. A waiting result returns that starting checkpoint: do not replace it with an intermediate preview. The journal is required continuation data and must be retained with the checkpoint. Stable IDs include turn/segment and deterministic invocation identity. There is no live continuation or request-held promise while waiting. Runtimes serialize work per session, check cancellation before effects and before settlement, and fence ownership. Lost provider acknowledgement becomes uncertain; do not repeat it merely because a worker restarts.
 
@@ -22,6 +22,6 @@ Host resolveEffect must bind the effect ID to the original request and reject dr
 
 ## Definitions, validation, compatibility
 
-`/define` is execution-free and browser-bundleable; Agent has no `.run()`. Explicit local execution uses `/run` run + bindingFromAgent(agent.build()). `/contracts` never imports checkpoint internals. Tools and before/after hooks are supported remotely. Arbitrary legacy middleware closures are rejected for durable definitions because they cannot be reconstructed from manifests. JSON schemas are reconstructed through Zod's JSON Schema importer; unsupported schemas fail closed. The original manifest hash must survive reconstruction. Model configuration is host-owned. The executor validates its local manifest hash and implementationVersion before claiming and validates tool inputs/outputs locally.
+`/define` is execution-free and browser-bundleable; Agent has no `.run()`. Explicit local execution uses `/run` run + bindingFromAgent(agent.build()). `/contracts` never imports checkpoint internals. Tools and before/after hooks are supported remotely. Arbitrary legacy middleware closures are rejected for durable definitions because they cannot be reconstructed from manifests. JSON schemas are reconstructed through Zod's JSON Schema importer; unsupported schemas fail closed. The original manifest document must survive reconstruction. Runtime is the only hasher: it hashes the accepted manifest and pins that digest on the session and on each action. Agents do not hash. Model configuration is host-owned. The executor claims by agent id. Runtime checks a successful tool result against the output schema copied onto the action and stores a schema mismatch as a failed outcome on a completed action.
 
 No session migration, arbitrary checkpoint migration, broad model-support, or conformance claims follow from compiling this interface. Studio and conformance tooling remain outside production harness.

package/dist/definition/registry.js

@@ -8,7 +8,7 @@ export class ToolRegistry {
     owners = new WeakMap();
     constructor(middleware, snapshots) {
         for (const capability of middleware) {
-            for (const tool of capability.tools ?? []) {
+            for (const tool of [...(capability.tools ?? []), ...(capability.sessionTools ?? [])]) {
                 const key = JSON.stringify([capability.id, tool.name]);
                 if (this.tools.has(key) || this.owners.has(tool))
                     throw new HarnessError("tool.invalid", `Duplicate registered tool '${tool.name}' in '${capability.id}'`);

package/dist/loop/step/dynamics.js

@@ -42,13 +42,15 @@ export async function applyBeforeModelCall(ctx, configuration) {
         }
         if (patch.tools) {
             for (const [name, on] of Object.entries(patch.tools)) {
-                const known = ctx.agent.manifest.capabilities.some((cap) => cap.tools?.some((tool) => tool.name === name));
+                const known = ctx.agent.manifest.capabilities.some((cap) => cap.tools?.some((tool) => tool.name === name) ||
+                    ctx.agent.implementations[cap.id]?.tools?.[name] !== undefined);
                 if (!known)
                     throw new HarnessError("configuration.invalid", `beforeModelCall referenced unknown tool '${name}'`);
                 if (!agentLevel) {
-                    const owned = ctx.agent.manifest.capabilities
+                    const declared = ctx.agent.manifest.capabilities
                         .find((cap) => cap.id === id)
                         ?.tools?.some((tool) => tool.name === name);
+                    const owned = declared || ctx.agent.implementations[id]?.tools?.[name] !== undefined;
                     if (!owned)
                         throw new HarnessError("configuration.invalid", `Capability '${id}' beforeModelCall may only toggle its own tools`);
                 }

package/dist/run/durable.d.ts

@@ -50,6 +50,14 @@ export type DurableResult = {
     readonly checkpoint: DurableCheckpoint;
     readonly result: RunResult<unknown>;
 };
+/** Discovered tool advertised for this execution. It is not part of the hashed manifest. */
+export interface DurableSessionTool {
+    readonly capabilityId: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema: JsonObject;
+    readonly outputSchema?: JsonObject;
+}
 export declare function createDurableCheckpoint(input: {
     manifest: AgentManifest;
     sessionId: string;
@@ -68,4 +76,5 @@ export declare function runDurable(options: {
     checkpoint: DurableCheckpoint;
     host: DurableHost;
     signal?: AbortSignal;
+    sessionTools?: readonly DurableSessionTool[];
 }): Promise<DurableResult>;

package/dist/run/durable.js

@@ -72,54 +72,59 @@ export async function runDurable(options) {
         return result.outcome;
     };
     let patchTail = Promise.resolve();
+    const hostedTool = (capabilityId, tool) => ({
+        name: tool.name,
+        ...(tool.description === undefined ? {} : { description: tool.description }),
+        inputSchema: schemaFromJSON(tool.inputSchema),
+        ...(tool.outputSchema ? { outputSchema: schemaFromJSON(tool.outputSchema) } : {}),
+        async execute(args, ctx) {
+            const previous = patchTail;
+            let release;
+            patchTail = new Promise((resolve) => {
+                release = resolve;
+            });
+            try {
+                const outcome = await effect("tool", args, {
+                    executionId: ctx.executionId,
+                    turnId: ctx.turnId,
+                    stepId: ctx.stepId,
+                    callId: ctx.callId,
+                    invocationId: ctx.invocationId,
+                    idempotencyKey: ctx.idempotencyKey,
+                    info: ctx.info,
+                    state: ctx.state.entries(),
+                    resume: ctx.resume,
+                }, capabilityId, tool.name, ctx.invocationId);
+                // Apply concurrently resolved patches in manifest call order, independent of host I/O timing.
+                await previous;
+                for (const [key, value] of Object.entries(outcome.statePatch ?? {}))
+                    ctx.state.set(key, value);
+                const value = outcome.value;
+                return value?.kind === "interaction-required"
+                    ? {
+                        ...value,
+                        interaction: {
+                            ...value.interaction,
+                            id: `${checkpoint.turnId}:${checkpoint.segment}:interaction:${ctx.invocationId}`,
+                        },
+                    }
+                    : value;
+            }
+            finally {
+                await previous;
+                release();
+            }
+        },
+    });
     const implementations = {};
+    const sessionTools = options.sessionTools ?? [];
     for (const capability of manifest.capabilities) {
         const tools = {};
         for (const tool of capability.tools ?? [])
-            tools[tool.name] = {
-                name: tool.name,
-                ...(tool.description === undefined ? {} : { description: tool.description }),
-                inputSchema: schemaFromJSON(tool.inputSchema),
-                ...(tool.outputSchema ? { outputSchema: schemaFromJSON(tool.outputSchema) } : {}),
-                async execute(args, ctx) {
-                    const previous = patchTail;
-                    let release;
-                    patchTail = new Promise((resolve) => {
-                        release = resolve;
-                    });
-                    try {
-                        const outcome = await effect("tool", args, {
-                            executionId: ctx.executionId,
-                            turnId: ctx.turnId,
-                            stepId: ctx.stepId,
-                            callId: ctx.callId,
-                            invocationId: ctx.invocationId,
-                            idempotencyKey: ctx.idempotencyKey,
-                            info: ctx.info,
-                            state: ctx.state.entries(),
-                            resume: ctx.resume,
-                        }, capability.id, tool.name, ctx.invocationId);
-                        // Apply concurrently resolved patches in manifest call order, independent of host I/O timing.
-                        await previous;
-                        for (const [key, value] of Object.entries(outcome.statePatch ?? {}))
-                            ctx.state.set(key, value);
-                        const value = outcome.value;
-                        return value?.kind === "interaction-required"
-                            ? {
-                                ...value,
-                                interaction: {
-                                    ...value.interaction,
-                                    id: `${checkpoint.turnId}:${checkpoint.segment}:interaction:${ctx.invocationId}`,
-                                },
-                            }
-                            : value;
-                    }
-                    finally {
-                        await previous;
-                        release();
-                    }
-                },
-            };
+            tools[tool.name] = hostedTool(capability.id, tool);
+        for (const tool of sessionTools)
+            if (tool.capabilityId === capability.id)
+                tools[tool.name] = hostedTool(capability.id, tool);
         implementations[capability.id] = {
             tools,
             ...(capability.beforeModelCall
@@ -135,7 +140,14 @@ export async function runDurable(options) {
                 : {}),
         };
     }
-    const definition = definitionFor(agentFrom(manifest, implementations));
+    const definition = definitionFor(agentFrom(manifest, implementations, sessionTools.length === 0
+        ? undefined
+        : {
+            sessionTools: sessionTools.map((tool) => ({
+                capabilityId: tool.capabilityId,
+                name: tool.name,
+            })),
+        }));
     // Manifest reconstruction must retain definition identity, including schemas and instructions.
     if (definition.hash !== checkpoint.manifestHash)
         throw new HarnessError("execution.incompatible", "Reconstructed definition hash mismatch");

package/dist/run/index.d.ts

@@ -29,5 +29,5 @@ export declare function bindingFromAgent(agent: BuiltAgent): RunBinding;
 export { checkCompatibility, createExecutionState, validateExecutionState, execute };
 export type { Implementations, ExecutionState, RunResult, RunOptions };
 export { createDurableCheckpoint, runDurable } from "./durable.js";
-export type { DurableCheckpoint, HostEffect, EffectResolution, DurableHost, DurableResult, } from "./durable.js";
+export type { DurableCheckpoint, DurableSessionTool, HostEffect, EffectResolution, DurableHost, DurableResult, } from "./durable.js";
 export type { ModelAdapter, ModelCandidate, ModelCall, ModelRequest } from "@nylorun/core/define";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/harness",
-  "version": "0.15.0-beta",
+  "version": "0.16.0-beta",
   "description": "Nylorun's TypeScript agent execution engine. See github.com/nylorun/harness.",
   "type": "module",
   "license": "Apache-2.0",
@@ -70,15 +70,15 @@
   "devDependencies": {
     "@types/node": "^26.5.0",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "prettier": "^3.9.6",
+    "prettier": "^3.9.8",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "vitest": "^5.0.0",
-    "zod": "^4.1.12"
+    "vitest": "^5.0.1",
+    "zod": "^4.6.5"
   },
   "dependencies": {
-    "@nylorun/core": "0.1.1-beta"
+    "@nylorun/core": "0.2.0-beta"
   },
   "peerDependencies": {
-    "zod": "^4.5.4"
+    "zod": "^4.6.5"
   }
 }