@nylorun/agents 0.0.0-bootstrap → 0.2.0-beta

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @nylorun/agents
+
+## 0.2.0-beta
+
+### Minor Changes
+
+- 41e613c: Ship the local SDK registry workflow with an independent SQLite Runtime, connected tool executor, authenticated Studio proxy, and a text-and-tool starter. Replace the legacy Hono starter and AG-UI transport. Require Node 24 and include the SDK in exact release compatibility pins.
+
+  Break the Harness execution import from `/engine` to `/run` and rename hosted execution APIs to durable execution APIs, including RunBinding, BoundRunOptions, and createRunState. Update all consumers without compatibility aliases; retain persisted checkpoint fields and version pins.
+
+- 2898d02: Extract shared definitions and contracts into core and local orchestration into
+  CLI. Harness becomes execution-only; the SDK no longer installs the engine and
+  Runtime no longer depends on the SDK. Author applications through agents and
+  install cli for the unchanged nylorun commands. See the package architecture and
+  migration guide. Cloud installs published packages from npm independently.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [2898d02]
+  - @nylorun/core@0.1.1-beta
+
+## 0.1.0-beta.1
+
+Initial session SDK and connected SSE executor.

package/LICENSE

@@ -0,0 +1,192 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      Copyright 2026 Nylo
+
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+         http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.

package/README.md

@@ -0,0 +1,60 @@
+# @nylorun/agents
+
+One application install provides definition authoring, a session client, and a connected customer executor. This beta is currently built locally; no packages were published in this pass. Use the workspace or install packed SDK and core artifacts together until publishing is enabled.
+
+```ts
+import { Agent, createClient, connectAgents, tool } from "@nylorun/agents";
+import { z } from "zod";
+
+const assistant = Agent({
+  id: "assistant",
+  name: "Assistant",
+  instructions: "Use the available tools.",
+  tools: [
+    tool({
+      name: "lookup",
+      input: z.object({ id: z.string() }),
+      async run({ id }, ctx) {
+        return { id, owner: ctx.info };
+      },
+    }),
+  ],
+});
+
+// Run these application operations on your trusted backend.
+const client = createClient({
+  url: process.env.NYLORUN_RUNTIME_URL,
+  key: process.env.NYLORUN_SERVER_KEY,
+});
+await client.saveAgent(assistant, { implementationVersion: "app-1" });
+const session = await client.createSession({
+  agentId: assistant.id,
+  ownerUserId: authenticatedUser.id,
+});
+await session.input("Look up item 123", { idempotencyKey: requestId });
+const history = await session.history();
+
+// Customer executor process: credential is separately scoped by the Runtime.
+const connection = connectAgents({
+  agents: [assistant],
+  implementationVersion: "app-1",
+  runtime: {
+    url: process.env.NYLORUN_RUNTIME_URL,
+    key: process.env.NYLORUN_EXECUTOR_KEY,
+  },
+  onError: console.error,
+});
+await connection.ready;
+// On shutdown:
+await connection.close();
+```
+
+Use `session.observe({ cursor, signal })` for resumable canonical events, `session.inspect()` for waiting/uncertain state, and `approve`, `respond`, or `cancel` with an explicit stable idempotency key. Retry the same semantic command with the same key. `ownerUserId` must come from trusted server authentication. Application credentials are not browser credentials; browser applications need an authorized backend. Definition authoring is browser-bundleable.
+
+The Runtime destination is explicit, or defaults from `NYLORUN_RUNTIME_URL`. Application and executor keys default from `NYLORUN_SERVER_KEY` and `NYLORUN_EXECUTOR_KEY`. Implementation version defaults from `NYLORUN_IMPLEMENTATION_VERSION`, then `dev`. A host must provision executor scope for the exact agent ID, manifest hash and implementation version. Model selection and model credentials belong to the Runtime.
+
+`connectAgents({ agents })` opens authenticated fetch SSE before discovering actions, rediscovers after reconnection, and claims only matching definitions. It renews leases while executing, then retries HTTP result delivery with the same recorded outcome and idempotency key. Reconnect delay is bounded at 30 seconds. Notifications confer no execution authority. There is no periodic action-discovery polling. Close aborts the stream, HTTP requests and lease timers and signals running functions; JavaScript cannot forcibly terminate a function that ignores its signal. The host makes expired in-flight actions uncertain instead of automatically repeating external effects.
+
+Tools receive state, info, identity, resume, signal, approval/response helpers and memoized `step`. Step outcomes survive a persisted wait result; they do not establish exactly-once external effects after an unacknowledged crash. `sleep` and `waitFor` currently return inspectable deferred outcomes; automatic timer/event wakeups remain runtime implementation work. Remote `onModelCall` convenience and progress-event transport are not supplied in this pass. Arbitrary middleware closures are rejected for durable definitions; use before/after hooks. Agent definitions have no `.run()`; explicit local execution is available through `@nylorun/harness/run`.
+
+The SDK depends only on core within the Nylorun packages; installing it does not install harness. Use `/define`, `/client`, or `/executor` for focused imports, or the root for convenience. Studio uses `/client`. See [the adopted host contract](../harness/HOST_CONTRACT.md) and the repository handoff for the verification boundary.

package/dist/client.d.ts

@@ -0,0 +1,121 @@
+import type { AgentManifest, BuiltAgent, JsonValue } from "@nylorun/core/define";
+import { type SessionCommand } from "@nylorun/core/contracts";
+import { Transport, type Destination } from "./http.js";
+export interface AgentSource {
+    readonly id: string;
+    readonly manifest: AgentManifest;
+    readonly hash: string;
+    build?(): BuiltAgent;
+}
+export interface SessionView {
+    id: string;
+    agentId: string;
+    ownerUserId: string;
+    status: string;
+    activeTurnId: string | null;
+    [key: string]: unknown;
+}
+export declare class AgentsClient {
+    readonly transport: Transport;
+    constructor(destination?: Destination);
+    listAgents(options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        agents: {
+            manifest: AgentManifest;
+        }[];
+    }>;
+    listSessions(options?: {
+        agentId?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        sessions: SessionView[];
+    }>;
+    saveAgent(agent: AgentSource, options: {
+        implementationVersion: string;
+        requestId?: string;
+    }): Promise<unknown>;
+    createSession(options: {
+        id?: string;
+        agentId: string;
+        ownerUserId: string;
+        info?: Record<string, unknown>;
+        requestId?: string;
+    }): Promise<SessionClient>;
+    session(sessionId: string): SessionClient;
+}
+export type CommandOptions = {
+    idempotencyKey: string;
+    requestId?: string;
+    signal?: AbortSignal;
+};
+export declare class SessionClient {
+    private readonly transport;
+    readonly id: string;
+    constructor(transport: Transport, id: string);
+    private get path();
+    inspect(signal?: AbortSignal): Promise<SessionView>;
+    command(command: SessionCommand, signal?: AbortSignal): Promise<{
+        status: "accepted";
+        turnId: string | null;
+        cursor: string | null;
+        requestId: string;
+    }>;
+    input(content: string, options: CommandOptions): Promise<{
+        status: "accepted";
+        turnId: string | null;
+        cursor: string | null;
+        requestId: string;
+    }>;
+    approve(interactionId: string, approved: boolean, options: CommandOptions): Promise<{
+        status: "accepted";
+        turnId: string | null;
+        cursor: string | null;
+        requestId: string;
+    }>;
+    respond(interactionId: string, value: JsonValue, options: CommandOptions): Promise<{
+        status: "accepted";
+        turnId: string | null;
+        cursor: string | null;
+        requestId: string;
+    }>;
+    cancel(options: CommandOptions & {
+        reason?: string;
+    }): Promise<{
+        status: "accepted";
+        turnId: string | null;
+        cursor: string | null;
+        requestId: string;
+    }>;
+    history(options?: {
+        cursor?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        items: {
+            eventId: string;
+            sessionId: string;
+            turnId: string | null;
+            cursor: string;
+            createdAt: string;
+            type: string;
+            payload: unknown;
+        }[];
+        cursor: string | null;
+    }>;
+    observe(options?: {
+        cursor?: string;
+        signal?: AbortSignal;
+    }): AsyncGenerator<{
+        eventId: string;
+        sessionId: string;
+        turnId: string | null;
+        cursor: string;
+        createdAt: string;
+        type: string;
+        payload: unknown;
+    }, void, unknown>;
+}
+export declare function createClient(destination?: Destination): AgentsClient;
+export { RuntimeError } from "./http.js";
+export type { Destination } from "./http.js";
+export type { LiveEvent } from "@nylorun/core/contracts";

package/dist/client.js

@@ -0,0 +1,103 @@
+import { LiveEventSchema, SessionItemsResponseSchema, } from "@nylorun/core/contracts";
+import { Transport, id, segment } from "./http.js";
+import { observeSSE } from "./sse.js";
+export class AgentsClient {
+    transport;
+    constructor(destination = {}) {
+        this.transport = new Transport(destination);
+    }
+    listAgents(options = {}) {
+        return this.transport.json("/v1/agents", "GET", undefined, options.signal);
+    }
+    listSessions(options = {}) {
+        const query = options.agentId
+            ? `?agentId=${encodeURIComponent(options.agentId)}`
+            : "";
+        return this.transport.json(`/v1/sessions${query}`, "GET", undefined, options.signal);
+    }
+    saveAgent(agent, options) {
+        return this.transport.json(`/v1/agents/${segment(agent.id)}`, "PUT", {
+            requestId: options.requestId ?? id(),
+            manifest: agent.manifest,
+            implementationVersion: options.implementationVersion,
+        });
+    }
+    async createSession(options) {
+        const sessionId = options.id ?? id();
+        await this.transport.json(`/v1/sessions/${segment(sessionId)}`, "PUT", {
+            requestId: options.requestId ?? id(),
+            agentId: options.agentId,
+            ownerUserId: options.ownerUserId,
+            ...(options.info ? { info: options.info } : {}),
+        });
+        return this.session(sessionId);
+    }
+    session(sessionId) {
+        return new SessionClient(this.transport, sessionId);
+    }
+}
+export class SessionClient {
+    transport;
+    id;
+    constructor(transport, id) {
+        this.transport = transport;
+        this.id = id;
+    }
+    get path() {
+        return `/v1/sessions/${segment(this.id)}`;
+    }
+    inspect(signal) {
+        return this.transport.json(this.path, "GET", undefined, signal);
+    }
+    command(command, signal) {
+        return this.transport.json(`${this.path}/commands`, "POST", command, signal);
+    }
+    input(content, options) {
+        return this.command({
+            type: "message",
+            content,
+            requestId: options.requestId ?? id(),
+            idempotencyKey: options.idempotencyKey,
+        }, options.signal);
+    }
+    approve(interactionId, approved, options) {
+        return this.command({
+            type: "approve",
+            interactionId,
+            approved,
+            requestId: options.requestId ?? id(),
+            idempotencyKey: options.idempotencyKey,
+        }, options.signal);
+    }
+    respond(interactionId, value, options) {
+        return this.command({
+            type: "respond",
+            interactionId,
+            value,
+            requestId: options.requestId ?? id(),
+            idempotencyKey: options.idempotencyKey,
+        }, options.signal);
+    }
+    cancel(options) {
+        return this.command({
+            type: "cancel",
+            requestId: options.requestId ?? id(),
+            idempotencyKey: options.idempotencyKey,
+            ...(options.reason ? { reason: options.reason } : {}),
+        }, options.signal);
+    }
+    async history(options = {}) {
+        return SessionItemsResponseSchema.parse(await this.transport.json(`${this.path}/items${options.cursor ? `?cursor=${encodeURIComponent(options.cursor)}` : ""}`, "GET", undefined, options.signal));
+    }
+    async *observe(options = {}) {
+        for await (const frame of observeSSE(this.transport, `${this.path}/events`, options)) {
+            if (frame.event === "heartbeat" || frame.event === "ready")
+                continue;
+            yield LiveEventSchema.parse(JSON.parse(frame.data));
+        }
+    }
+}
+export function createClient(destination = {}) {
+    return new AgentsClient(destination);
+}
+export { RuntimeError } from "./http.js";

package/dist/define.d.ts

@@ -0,0 +1 @@
+export * from "@nylorun/core/define";

package/dist/define.js

@@ -0,0 +1 @@
+export * from "@nylorun/core/define";

package/dist/execute-action.d.ts

@@ -0,0 +1,4 @@
+import { type BuiltAgent } from "@nylorun/core/define";
+import type { Action, ActionOutcome } from "@nylorun/core/contracts";
+/** Executes code only after a host-issued claim. No engine dependency. */
+export declare function executeAction(action: Action, agent: BuiltAgent, signal: AbortSignal): Promise<ActionOutcome>;

package/dist/execute-action.js

@@ -0,0 +1,190 @@
+import { implementationsFor, isToolError, normalizeToolDefinition, normalizedSchemasFor, } from "@nylorun/core/define";
+class Suspend {
+    outcome;
+    constructor(outcome) {
+        this.outcome = outcome;
+    }
+}
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};
+/** Executes code only after a host-issued claim. No engine dependency. */
+export async function executeAction(action, agent, signal) {
+    const impl = implementationsFor(agent)[action.capabilityId];
+    if (!impl)
+        throw new Error(`No capability ${action.capabilityId}`);
+    if (action.kind === "beforeModelCall") {
+        if (!impl.beforeModelCall)
+            throw new Error("Missing beforeModelCall implementation");
+        try {
+            return { value: (await impl.beforeModelCall(action.input)) ?? {} };
+        }
+        catch (error) {
+            return { value: { block: message(error) } };
+        }
+    }
+    if (action.kind === "afterModelCall") {
+        if (!impl.afterModelCall)
+            throw new Error("Missing afterModelCall implementation");
+        try {
+            return {
+                value: (await impl.afterModelCall(action.input, action.context)) ?? {},
+            };
+        }
+        catch (error) {
+            return { value: { block: message(error) } };
+        }
+    }
+    const raw = impl.tools?.[action.toolName ?? ""];
+    if (!raw)
+        throw new Error("Missing tool implementation");
+    const tool = normalizeToolDefinition(raw);
+    const schemas = normalizedSchemasFor(tool);
+    const input = schemas.inputSchema.validate(action.input);
+    if (!input.ok)
+        return {
+            value: {
+                kind: "failed",
+                code: "tool.invalid-input",
+                message: JSON.stringify(input.issues),
+            },
+        };
+    const ctx = action.context;
+    const state = { ...object(ctx.state) };
+    const statePatch = {};
+    const resume = object(ctx.resume);
+    const token = object(resume.token);
+    const memo = object(token._nylorun);
+    const steps = { ...object(memo.steps) };
+    const answers = { ...object(memo.answers) };
+    let waitIndex = 0;
+    let gateApproved = Boolean(memo.gateApproved) ||
+        Boolean(memo.approvalGate && resume.kind === "approval" && resume.approved);
+    const durableToken = (extra = {}) => ({
+        _nylorun: { steps, answers, waitIndex, gateApproved, ...extra },
+    });
+    const wait = async (kind, prompt, metadata) => {
+        const index = String(waitIndex++);
+        if (index in answers)
+            return answers[index];
+        if (!memo.approvalGate &&
+            resume.kind === kind &&
+            Number(memo.waitIndex ?? 0) === Number(index)) {
+            const answer = kind === "approval" ? Boolean(resume.approved) : resume.value;
+            answers[index] = answer;
+            return answer;
+        }
+        throw new Suspend({
+            kind: "interaction-required",
+            interaction: { kind, prompt, ...(metadata ? { metadata } : {}) },
+            token: {
+                _nylorun: { steps, answers, waitIndex: Number(index), gateApproved },
+            },
+        });
+    };
+    const context = {
+        executionId: String(ctx.executionId ?? action.sessionId),
+        turnId: String(ctx.turnId ?? action.turnId),
+        stepId: String(ctx.stepId ?? ""),
+        callId: String(ctx.callId ?? action.actionId),
+        invocationId: String(ctx.invocationId ?? action.actionId),
+        idempotencyKey: String(ctx.idempotencyKey ?? action.actionId),
+        signal,
+        info: ctx.info,
+        session: { id: action.sessionId },
+        ...(ctx.resume ? { resume: ctx.resume } : {}),
+        state: {
+            get: (key) => state[key],
+            set: (key, value) => {
+                state[key] = value;
+                statePatch[key] = value;
+            },
+            entries: () => ({ ...state }),
+        },
+        progress() {
+            /* Canonical events are host-owned; progress transport is deferred. */
+        },
+        ask: (prompt, options) => wait("response", prompt, options),
+        approve: (prompt) => wait("approval", prompt),
+        sleep: async (duration) => {
+            throw new Suspend({
+                kind: "deferred",
+                token: durableToken({ wait: { kind: "sleep", duration } }),
+            });
+        },
+        waitFor: async (event, options) => {
+            throw new Suspend({
+                kind: "deferred",
+                token: durableToken({ wait: { kind: "waitFor", event, ...options } }),
+            });
+        },
+        step: async (name, fn) => {
+            if (Object.prototype.hasOwnProperty.call(steps, name))
+                return steps[name];
+            signal.throwIfAborted();
+            const value = await fn();
+            // Memoized values are durable only with a persisted action outcome. Interrupted actions stay uncertain.
+            steps[name] = JSON.parse(JSON.stringify(value ?? null));
+            return value;
+        },
+    };
+    try {
+        signal.throwIfAborted();
+        if (tool.approval && !gateApproved) {
+            const approval = await tool.approval(input.value);
+            if (approval)
+                throw new Suspend({
+                    kind: "interaction-required",
+                    interaction: {
+                        kind: "approval",
+                        prompt: typeof approval === "string" ? approval : `Approve ${tool.name}?`,
+                    },
+                    token: durableToken({ approvalGate: true }),
+                });
+            gateApproved = true;
+        }
+        if (resume.kind === "approval" && resume.approved === false)
+            return { value: { kind: "denied", reason: "Approval denied" } };
+        const value = await tool.execute(input.value, context);
+        const tagged = object(value);
+        let outcome;
+        if ([
+            "completed",
+            "failed",
+            "denied",
+            "interaction-required",
+            "deferred",
+        ].includes(tagged.kind))
+            outcome = value;
+        else
+            outcome = { kind: "completed", output: value ?? null };
+        if (outcome.kind === "completed" && schemas.outputSchema) {
+            const parsed = schemas.outputSchema.validate(outcome.output);
+            outcome = parsed.ok
+                ? { ...outcome, output: parsed.value }
+                : {
+                    kind: "failed",
+                    code: "tool.invalid-output",
+                    message: JSON.stringify(parsed.issues),
+                };
+        }
+        return { value: outcome, statePatch };
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw signal.reason;
+        return {
+            value: error instanceof Suspend
+                ? error.outcome
+                : {
+                    kind: "failed",
+                    code: isToolError(error) ? error.code : "tool.execution-failed",
+                    message: message(error),
+                },
+            statePatch,
+        };
+    }
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/executor.d.ts

@@ -0,0 +1,15 @@
+import type { AgentSource } from "./client.js";
+import { type Destination } from "./http.js";
+export interface ConnectOptions {
+    agents: readonly AgentSource[];
+    runtime?: Destination;
+    implementationVersion?: string;
+    onError?: (error: unknown) => void;
+}
+export interface AgentConnection {
+    /** Settles after authenticated SSE is established and initial discovery succeeds. */
+    readonly ready: Promise<void>;
+    /** Abort subscriptions and leases. Running user code receives an AbortSignal. */
+    close(): Promise<void>;
+}
+export declare function connectAgents(options: ConnectOptions): AgentConnection;

package/dist/executor.js

@@ -0,0 +1,215 @@
+import { AgentManifestSchema, ActionSchema, ActionClaimResponseSchema, } from "@nylorun/core/contracts";
+import { Transport, RuntimeError, delay, env, id, segment, } from "./http.js";
+import { readSSE } from "./sse.js";
+import { executeAction } from "./execute-action.js";
+export function connectAgents(options) {
+    const transport = new Transport(options.runtime, "executor");
+    const version = options.implementationVersion ??
+        env("NYLORUN_IMPLEMENTATION_VERSION") ??
+        "dev";
+    const agents = new Map();
+    for (const source of options.agents) {
+        const built = source.build?.() ?? source;
+        AgentManifestSchema.parse(built.manifest);
+        if (agents.has(built.id))
+            throw new Error(`Duplicate connected agent ${built.id}`);
+        agents.set(built.id, built);
+    }
+    if (!agents.size)
+        throw new Error("connectAgents requires at least one agent");
+    const controller = new AbortController();
+    const signal = controller.signal;
+    const active = new Map();
+    let resolveReady;
+    let rejectReady;
+    const ready = new Promise((resolve, reject) => {
+        resolveReady = resolve;
+        rejectReady = reject;
+    });
+    // Avoid an unhandled rejection for callers that immediately close the handle.
+    void ready.catch(() => { });
+    const report = (error) => {
+        try {
+            options.onError?.(error);
+        }
+        catch { }
+    };
+    let discovering = false, dirty = false;
+    const discover = async () => {
+        dirty = true;
+        if (discovering)
+            return;
+        discovering = true;
+        try {
+            while (dirty && !signal.aborted) {
+                dirty = false;
+                const response = await transport.json("/v1/actions", "GET", undefined, signal);
+                for (const item of response.actions) {
+                    const action = ActionSchema.parse(item);
+                    const agent = agents.get(action.agentId);
+                    if (!agent ||
+                        agent.hash !== action.manifestHash ||
+                        action.implementationVersion !== version ||
+                        action.status !== "pending" ||
+                        active.has(action.actionId))
+                        continue;
+                    const work = new AbortController();
+                    active.set(action.actionId, work);
+                    let delivered = false;
+                    void processAction(action, agent, work)
+                        .then(() => {
+                        delivered = true;
+                    })
+                        .catch((error) => {
+                        if (!signal.aborted)
+                            report(error);
+                    })
+                        .finally(() => {
+                        active.delete(action.actionId);
+                        // Completion-driven discovery drains bounded server pages without periodic polling.
+                        if (delivered && !signal.aborted)
+                            void discover().catch(report);
+                    });
+                }
+            }
+        }
+        finally {
+            discovering = false;
+        }
+    };
+    const processAction = async (action, agent, work) => {
+        const stop = () => work.abort(signal.reason);
+        signal.addEventListener("abort", stop, { once: true });
+        let renewal;
+        let renewing = true;
+        let wakeRenewal;
+        try {
+            const claim = ActionClaimResponseSchema.parse(await transport.json(`/v1/actions/${segment(action.actionId)}/claim`, "POST", {
+                requestId: id(),
+                manifestHash: agent.hash,
+                implementationVersion: version,
+            }, work.signal));
+            if (claim.action.actionId !== action.actionId ||
+                claim.action.manifestHash !== agent.hash ||
+                claim.action.implementationVersion !== version)
+                throw new Error("Claim definition mismatch");
+            let expires = Date.parse(claim.leaseExpiresAt);
+            renewal = (async () => {
+                while (renewing && !work.signal.aborted) {
+                    const remaining = expires - Date.now();
+                    if (!Number.isFinite(remaining) || remaining <= 0)
+                        throw new Error("Executor lease expired");
+                    await new Promise((resolve) => {
+                        const finish = () => {
+                            clearTimeout(timer);
+                            work.signal.removeEventListener("abort", finish);
+                            resolve();
+                        };
+                        const timer = setTimeout(finish, Math.max(50, Math.floor(remaining / 3)));
+                        wakeRenewal = finish;
+                        work.signal.addEventListener("abort", finish, { once: true });
+                    });
+                    if (!renewing || work.signal.aborted)
+                        return;
+                    const renewed = await transport.json(`/v1/actions/${segment(action.actionId)}/heartbeat`, "POST", {
+                        requestId: id(),
+                        claimId: claim.claimId,
+                        generation: claim.generation,
+                    }, work.signal);
+                    expires = Date.parse(renewed.leaseExpiresAt);
+                }
+            })().catch((error) => {
+                if (renewing && !work.signal.aborted) {
+                    work.abort(error);
+                    report(error);
+                }
+            });
+            const outcome = await executeAction(claim.action, agent, work.signal);
+            work.signal.throwIfAborted();
+            const command = {
+                type: "action_result",
+                requestId: id(),
+                idempotencyKey: `action:${action.actionId}:${claim.generation}`,
+                actionId: action.actionId,
+                claimId: claim.claimId,
+                generation: claim.generation,
+                outcome,
+            };
+            // Retrying delivery never re-invokes the tool/hook. Lost acknowledgements use the same receipt key.
+            for (let attempt = 0;; attempt++) {
+                try {
+                    await transport.json(`/v1/sessions/${segment(action.sessionId)}/commands`, "POST", command, work.signal);
+                    break;
+                }
+                catch (error) {
+                    if (work.signal.aborted ||
+                        attempt >= 4 ||
+                        (error instanceof RuntimeError &&
+                            error.status < 500 &&
+                            ![408, 429].includes(error.status)))
+                        throw error;
+                    await delay(Math.min(4000, 250 * 2 ** attempt), work.signal);
+                }
+            }
+        }
+        finally {
+            renewing = false;
+            wakeRenewal?.();
+            await renewal;
+            signal.removeEventListener("abort", stop);
+        }
+    };
+    const loop = (async () => {
+        let retry = 250;
+        while (!signal.aborted) {
+            const subscription = new AbortController();
+            const stop = () => subscription.abort(signal.reason);
+            signal.addEventListener("abort", stop, { once: true });
+            try {
+                const response = await transport.request("/v1/executors/connect", {
+                    signal: subscription.signal,
+                    headers: { Accept: "text/event-stream" },
+                });
+                if (!response.headers.get("content-type")?.includes("text/event-stream"))
+                    throw new Error("Executor endpoint did not return SSE");
+                // Subscription exists before initial discovery; notifications can safely accumulate in its stream.
+                await discover();
+                resolveReady();
+                for await (const frame of readSSE(response, subscription.signal)) {
+                    retry = 250;
+                    if (frame.event === "work_available" ||
+                        (frame.data && JSON.parse(frame.data).type === "work_available"))
+                        await discover();
+                }
+            }
+            catch (error) {
+                if (signal.aborted)
+                    break;
+                report(error);
+                if (error instanceof RuntimeError &&
+                    [400, 401, 403, 404].includes(error.status)) {
+                    rejectReady(error);
+                    controller.abort(error);
+                    break;
+                }
+            }
+            finally {
+                subscription.abort();
+                signal.removeEventListener("abort", stop);
+            }
+            if (!signal.aborted)
+                await delay(retry, signal).catch(() => { });
+            retry = Math.min(30000, retry * 2);
+        }
+        rejectReady(signal.reason ?? new Error("Executor connection closed"));
+    })();
+    return {
+        ready,
+        async close() {
+            controller.abort(new Error("Executor connection closed"));
+            for (const work of active.values())
+                work.abort(signal.reason);
+            await loop;
+        },
+    };
+}

package/dist/http.d.ts

@@ -0,0 +1,22 @@
+export interface Destination {
+    url?: string;
+    key?: string;
+    fetch?: typeof fetch;
+}
+export declare function env(name: string): string | undefined;
+export declare class RuntimeError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+export declare class Transport {
+    readonly url: string;
+    readonly key: string;
+    readonly fetcher: typeof fetch;
+    constructor(options?: Destination, role?: "server" | "executor");
+    request(path: string, init?: RequestInit): Promise<Response>;
+    json<T>(path: string, method?: string, body?: unknown, signal?: AbortSignal): Promise<T>;
+}
+export declare const id: () => `${string}-${string}-${string}-${string}-${string}`;
+export declare const segment: (value: string) => string;
+export declare function delay(ms: number, signal: AbortSignal): Promise<void>;

package/dist/http.js

@@ -0,0 +1,81 @@
+export function env(name) {
+    return typeof process !== "undefined" ? process.env[name] : undefined;
+}
+export class RuntimeError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`Runtime HTTP ${status}: ${JSON.stringify(body)}`);
+        this.status = status;
+        this.body = body;
+    }
+}
+export class Transport {
+    url;
+    key;
+    fetcher;
+    constructor(options = {}, role = "server") {
+        const url = options.url ?? env("NYLORUN_RUNTIME_URL");
+        const key = options.key ??
+            env(role === "server" ? "NYLORUN_SERVER_KEY" : "NYLORUN_EXECUTOR_KEY");
+        if (!url || !key)
+            throw new Error(`Set Runtime url and ${role} key explicitly or via NYLORUN_RUNTIME_URL / NYLORUN_${role.toUpperCase()}_KEY`);
+        const parsed = new URL(url);
+        if (!["http:", "https:"].includes(parsed.protocol))
+            throw new Error("Runtime requires an HTTP(S) URL");
+        this.url = url.replace(/\/$/, "");
+        this.key = key;
+        this.fetcher = options.fetch ?? globalThis.fetch;
+    }
+    async request(path, init = {}) {
+        const headers = new Headers(init.headers);
+        headers.set("Authorization", `Bearer ${this.key}`);
+        if (init.body)
+            headers.set("Content-Type", "application/json");
+        const response = await this.fetcher(this.url + path, {
+            ...init,
+            headers,
+            redirect: "error",
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            let body = text;
+            try {
+                body = JSON.parse(text);
+            }
+            catch { }
+            throw new RuntimeError(response.status, body);
+        }
+        return response;
+    }
+    async json(path, method = "GET", body, signal) {
+        const response = await this.request(path, {
+            method,
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            signal,
+        });
+        return response.status === 204
+            ? undefined
+            : response.json();
+    }
+}
+export const id = () => globalThis.crypto.randomUUID();
+export const segment = (value) => encodeURIComponent(value);
+export function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const stop = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", stop);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", stop);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", stop, { once: true });
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, capability, tool, defineSchema, ToolError, } from "@nylorun/core/define";
+export type { AgentOptions, AgentManifest, BuiltAgent, ToolDefinition, ToolExecutionContext, ToolOutcome, Patch, Decision, JsonValue, JsonObject, } from "@nylorun/core/define";
+export type { LiveEvent, SessionCommand, Action, ActionOutcome, } from "@nylorun/core/contracts";
+export { AgentsClient, SessionClient, createClient } from "./client.js";
+export type { AgentSource, SessionView, CommandOptions } from "./client.js";
+export { connectAgents } from "./executor.js";
+export type { ConnectOptions, AgentConnection } from "./executor.js";
+export { RuntimeError } from "./http.js";
+export type { Destination } from "./http.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+// Definition authoring and wire contracts are the only harness runtime imports.
+export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, capability, tool, defineSchema, ToolError, } from "@nylorun/core/define";
+export { AgentsClient, SessionClient, createClient } from "./client.js";
+export { connectAgents } from "./executor.js";
+export { RuntimeError } from "./http.js";

package/dist/sse.d.ts

@@ -0,0 +1,12 @@
+import { type Transport } from "./http.js";
+export interface SSEEvent {
+    event: string;
+    data: string;
+    id?: string;
+}
+/** Fetch-based SSE supports Authorization headers and works in browsers and Node. */
+export declare function readSSE(response: Response, signal: AbortSignal): AsyncGenerator<SSEEvent>;
+export declare function observeSSE(transport: Transport, path: string, options?: {
+    signal?: AbortSignal;
+    cursor?: string;
+}): AsyncGenerator<SSEEvent>;

package/dist/sse.js

@@ -0,0 +1,97 @@
+import { delay, RuntimeError } from "./http.js";
+/** Fetch-based SSE supports Authorization headers and works in browsers and Node. */
+export async function* readSSE(response, signal) {
+    if (!response.headers.get("content-type")?.includes("text/event-stream"))
+        throw new Error("Expected an SSE response");
+    if (!response.body)
+        throw new Error("SSE response has no body");
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let event = "message";
+    let data = [];
+    let lastId;
+    const abort = () => {
+        void reader.cancel().catch(() => { });
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    try {
+        while (!signal.aborted) {
+            const result = await reader.read();
+            if (result.done)
+                break;
+            buffer += decoder.decode(result.value, { stream: true });
+            if (buffer.length > 2_000_000)
+                throw new Error("SSE frame exceeds size limit");
+            let index;
+            while ((index = buffer.indexOf("\n")) >= 0) {
+                const line = buffer.slice(0, index).replace(/\r$/, "");
+                buffer = buffer.slice(index + 1);
+                if (line === "") {
+                    if (data.length)
+                        yield {
+                            event,
+                            data: data.join("\n"),
+                            ...(lastId === undefined ? {} : { id: lastId }),
+                        };
+                    event = "message";
+                    data = [];
+                    continue;
+                }
+                if (line.startsWith(":"))
+                    continue;
+                const colon = line.indexOf(":");
+                const field = colon < 0 ? line : line.slice(0, colon);
+                const value = colon < 0 ? "" : line.slice(colon + 1).replace(/^ /, "");
+                if (field === "event")
+                    event = value;
+                if (field === "data")
+                    data.push(value);
+                if (field === "id" && !value.includes("\0"))
+                    lastId = value;
+                if (data.reduce((n, v) => n + v.length, 0) > 2_000_000)
+                    throw new Error("SSE event exceeds size limit");
+            }
+        }
+    }
+    finally {
+        signal.removeEventListener("abort", abort);
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+export async function* observeSSE(transport, path, options = {}) {
+    const controller = new AbortController();
+    const signal = options.signal ?? controller.signal;
+    let cursor = options.cursor;
+    let retry = 250;
+    while (!signal.aborted) {
+        try {
+            const response = await transport.request(path, {
+                signal,
+                headers: {
+                    Accept: "text/event-stream",
+                    ...(cursor ? { "Last-Event-ID": cursor } : {}),
+                },
+            });
+            for await (const event of readSSE(response, signal)) {
+                retry = 250;
+                if (event.id)
+                    cursor = event.id;
+                yield event;
+            }
+        }
+        catch (error) {
+            if (signal.aborted)
+                return;
+            if (error instanceof RuntimeError &&
+                error.status >= 400 &&
+                error.status < 500 &&
+                ![408, 429].includes(error.status))
+                throw error;
+        }
+        if (!signal.aborted)
+            await delay(retry, signal).catch(() => { });
+        retry = Math.min(30000, retry * 2);
+    }
+}

package/package.json

@@ -1,12 +1,60 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.0.0-bootstrap",
-  "description": "Bootstrap placeholder for @nylorun/agents",
-  "main": "index.js",
+  "version": "0.2.0-beta",
+  "description": "Nylorun agent definitions, session client and connected executor",
+  "type": "module",
+  "license": "Apache-2.0",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./define": {
+      "types": "./dist/define.d.ts",
+      "import": "./dist/define.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./executor": {
+      "types": "./dist/executor.d.ts",
+      "import": "./dist/executor.js"
+    }
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsc -p tsconfig.json",
+    "check": "npm run build && npm test && node scripts/check-package.mjs",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@nylorun/core": "0.1.1-beta"
+  },
+  "peerDependencies": {
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "@types/node": "^24.0.0",
+    "vitest": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nylorun/harness.git",
+    "directory": "agents"
   },
-  "keywords": [],
-  "author": "",
-  "license": "MIT"
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
 }

package/index.js

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