@nylorun/agents 0.23.0-beta → 0.25.0-beta

package/dist/session-client.js

@@ -1,13 +1,14 @@
-import { SANDBOX_TOOL_NAMES, approvalRefusal, codeToolRefusal, delegateOf, isBuiltWorkflow, isSandboxToolName, } from "@nylorun/core/define";
+import { SANDBOX_TOOL_NAMES, isSandboxToolName } from "@nylorun/core/define";
 import { z } from "zod";
 import { SCOPES_HEADER, SUBJECT_HEADER } from "@nylorun/core/compatibility";
 import { SessionManifestViewSchema, SessionUsageTotalsSchema, ModelCallsPageSchema, ToolCallsPageSchema, TurnTraceSchema, parseSessionEvent, parseSubjectHeaders, } from "@nylorun/core/contracts";
 import { SessionsReadClient } from "./reads.js";
 import { AccessClient } from "./access.js";
-import { EnvironmentsClient } from "./environments.js";
+import { AgentInstancesClient } from "./agents.js";
+import { AgentManifestsClient } from "./agent-manifests.js";
 import { ArtifactsClient } from "./artifacts.js";
 import { FilesClient } from "./files.js";
-import { Transport, env, id, segment } from "./http.js";
+import { Transport, id, segment } from "./http.js";
 import { observeSSE } from "./sse.js";
 function sessionSandboxOf(transport, sessionId) {
     const call = (tool, args) => transport.json(`/v1/sessions/${segment(sessionId)}/sandbox/${segment(tool)}`, "POST", args);
@@ -30,33 +31,6 @@ function linkedSessionId(event) {
         ? sessionId
         : undefined;
 }
-/** The agent's declarations, then those of each agent it uses as a tool. */
-function declarationsOf(agent) {
-    if (isBuiltWorkflow(agent) || agent.manifest.kind === "workflow")
-        return [];
-    const built = agent.build?.() ?? agent;
-    if (isBuiltWorkflow(built))
-        return [];
-    const binding = built.getBinding?.();
-    if (!binding || !("parts" in binding))
-        return [];
-    const found = [...(binding.parts ?? [])];
-    for (const tool of binding.tools ?? []) {
-        const delegate = delegateOf(tool);
-        found.push(...(delegate?.agent?.getBinding().parts ?? []));
-        // A flow agent used as a tool: its agents' declarations.
-        for (const leaf of Object.values(delegate?.workflow?.getBinding().agents ?? {}))
-            found.push(...(leaf.parts ?? []));
-    }
-    return found;
-}
-/** The bytes of every skill file the agent's definition names, by `sha256:<hex>`. */
-function skillFilesOf(agent, into = new Map()) {
-    for (const item of declarationsOf(agent))
-        for (const [sha256, source] of Object.entries(item.skillFiles ?? {}))
-            into.set(sha256, source);
-    return into;
-}
 export class AgentsClient {
     transport;
     /** The subject this client acts for (`as`), or `undefined` for the principal itself. */
@@ -92,12 +66,19 @@ export class AgentsClient {
         return new AccessClient(this.transport);
     }
     /**
-     * Environments (protocol 11): `put` one by id (create, find or change), write its `secrets`,
-     * `list` them by label, `stop`, `reset` or `delete` one, or give a session its own with
-     * `forSession`.
+     * Agent manifests (protocol 16): `save` a manifest's next version (a v8 document, what
+     * `composeManifest` read, or a built agent with its runtime section), `plan` a save, read
+     * their versions.
      */
-    get environments() {
-        return new EnvironmentsClient(this.transport, (options) => this.createSession(options));
+    get agentManifests() {
+        return new AgentManifestsClient(this.transport);
+    }
+    /**
+     * Agents (protocol 16): `put` one by id from a saved manifest (create or find), write its
+     * `secrets`, `list` them, `stop`, `reset`, `fork` or `delete` one. Sessions run on them.
+     */
+    get agents() {
+        return new AgentInstancesClient(this.transport);
     }
     /** File artifacts: upload, list, download with Range, capability links (protocol 6). */
     get artifacts() {
@@ -114,54 +95,19 @@ export class AgentsClient {
     get sessions() {
         return new SessionsReadClient(this.transport);
     }
-    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);
     }
-    /**
-     * Registers the agent's definition (`PUT /v1/agents/{id}`), first uploading the skill files
-     * it names that the Runtime does not hold. A definition with a tool that runs your code
-     * (`tool({ run })`, a flow's tool stage) is refused before anything is sent: the Runtime runs
-     * agents from their manifests alone. `implementationVersion` defaults to
-     * `NYLORUN_IMPLEMENTATION_VERSION`, else `dev`. `dryRun` (protocol 14) runs every check and
-     * saves nothing; the skill files are still uploaded, since they are stored by content.
-     */
-    async saveAgent(agent, options = {}) {
-        const files = new Map();
-        if (isBuiltWorkflow(agent)) {
-            // A flow agent embeds its agents: one document, carrying their files.
-            for (const binding of Object.values(agent.getBinding().agents)) {
-                const leaf = { id: binding.manifest.id, manifest: binding.manifest, getBinding: () => binding };
-                skillFilesOf(leaf, files);
-            }
-        }
-        else {
-            skillFilesOf(agent, files);
-        }
-        const refusal = codeToolRefusal(agent.manifest) ??
-            approvalRefusal(agent.manifest);
-        if (refusal)
-            throw new Error(refusal);
-        await this.files.ensure(files);
-        return this.transport.json(`/v1/agents/${segment(agent.id)}${options.dryRun ? "?dryRun=true" : ""}`, "PUT", {
-            requestId: options.requestId ?? id(),
-            manifest: agent.manifest,
-            implementationVersion: options.implementationVersion ?? env("NYLORUN_IMPLEMENTATION_VERSION") ?? "dev",
-        });
-    }
     async createSession(options) {
         const sessionId = options.id ?? id();
         await this.transport.json(`/v1/sessions/${segment(sessionId)}`, "PUT", {
             requestId: options.requestId ?? id(),
-            agentId: options.agentId,
+            agent: options.agent,
             ownerUserId: options.ownerUserId,
             ...(options.info ? { info: options.info } : {}),
-            ...(options.environment === undefined ? {} : { environment: options.environment }),
         });
         return this.session(sessionId);
     }
@@ -189,6 +135,7 @@ export class SessionClient {
         const view = await this.inspect(signal);
         return view.waits ?? [];
     }
+    /** A message answers `queued` when it waits for the running turn (protocol 17). */
     command(command, signal) {
         return this.transport.json(`${this.path}/commands`, "POST", command, signal);
     }
@@ -201,6 +148,7 @@ export class SessionClient {
             type: "message",
             requestId: options.requestId ?? id(),
             idempotencyKey: options.idempotencyKey,
+            ...(options.delivery ? { delivery: options.delivery } : {}),
         };
         return this.command(typeof value === "string"
             ? { ...base, content: value }
@@ -217,6 +165,7 @@ export class SessionClient {
             requestId: options.requestId ?? id(),
             idempotencyKey: options.idempotencyKey,
             parts: [...parts],
+            ...(options.delivery ? { delivery: options.delivery } : {}),
         }, options.signal);
     }
     approve(interactionId, approved, options) {
@@ -266,7 +215,7 @@ export class SessionClient {
         return ModelCallsPageSchema.parse(await this.transport.json(`${this.path}/calls/model?${query}`, "GET", undefined, options.signal));
     }
     /**
-     * The session's tool calls (R5, Host feature `tool-calls`), in the order they were first sent:
+     * The session's tool calls (Host feature `tool-calls`), in the order they were first sent:
      * each one's tool, input, status and sends. `attempts` above 1: a crash re-sent it.
      */
     async toolCalls(options = {}) {
@@ -279,7 +228,7 @@ export class SessionClient {
         return ToolCallsPageSchema.parse(await this.transport.json(`${this.path}/calls/tool?${query}`, "GET", undefined, options.signal));
     }
     /**
-     * A turn's trace (R7, Host feature `traces`): its spans as OTLP/HTTP JSON (`resourceSpans`), as
+     * A turn's trace (Host feature `traces`): its spans as OTLP/HTTP JSON (`resourceSpans`), as
      * the Runtime posts them to an OTLP collector. Post it to a collector's `/v1/traces` to backfill
      * one, or read it without one.
      */
@@ -385,4 +334,5 @@ export class SessionClient {
 }
 export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
 export { AccessClient } from "./access.js";
-export { EnvironmentManifestsClient, EnvironmentSecretsClient, EnvironmentsClient, environmentFiles, environmentManifest, } from "./environments.js";
+export { AgentInstancesClient, AgentMemoriesClient, AgentSecretsClient, runtimeFiles } from "./agents.js";
+export { AgentManifestsClient, ManifestGapsError, agentManifest, requirementGaps } from "./agent-manifests.js";

package/dist/skills/index.d.ts

@@ -1,2 +1,2 @@
-export { loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, } from "./load.js";
+export { hashFolder, loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, } from "./load.js";
 export type { LoadedSkill, SkillDiagnostic } from "./load.js";

package/dist/skills/index.js

@@ -1 +1 @@
-export { loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, } from "./load.js";
+export { hashFolder, loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, } from "./load.js";

package/dist/skills/load.d.ts

@@ -14,6 +14,11 @@ export declare class SkillsError extends Error {
 export interface LoadedSkill {
     readonly name: string;
     readonly description: string;
+    /**
+     * The `runtime.secrets` slots its scripts read (`environment_secret` or `environment_variable`),
+     * from its SKILL.md's frontmatter `secrets`: sorted, each once.
+     */
+    readonly secrets?: readonly string[];
     /** Every file of the folder by its `/`-separated path, as `sha256:<hex>`. */
     readonly files: Readonly<Record<string, string>>;
     /** Each file's bytes, by `sha256:<hex>`, for the client to upload. */
@@ -32,8 +37,21 @@ export declare function loadSkillsFromDirectory(directory: string, diagnostics:
     readonly boundary?: string;
     readonly codePrefix?: string;
 }): Readonly<Record<string, LoadedSkill>>;
-export declare function parseSkill(text: string, directoryName: string): {
+/** A SKILL.md's frontmatter and instructions: `secrets` lists the secret slots its scripts read. */
+export interface ParsedSkill {
     name: string;
     description: string;
+    secrets?: string[];
     instructions: string;
-} | undefined;
+}
+export declare function parseSkill(text: string, directoryName: string): ParsedSkill | undefined;
+/**
+ * Every file of `directory` (a runtime section's `files` entry with `from`), hashed as a skill's
+ * folder is: each by its `/`-separated path, with where to read its bytes. Version control, OS
+ * and `.env` files are left out; a symbolic link outside `boundary` (default the folder) is
+ * skipped with a diagnostic.
+ */
+export declare function hashFolder(directory: string, diagnostics: SkillDiagnostic[], options?: {
+    readonly boundary?: string;
+    readonly codePrefix?: string;
+}): Pick<LoadedSkill, "files" | "sources">;

package/dist/skills/load.js

@@ -3,6 +3,7 @@ import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, r
 import { open } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { SKILL_ENTRY, skillFilePathIssue, } from "@nylorun/core/define";
+import { ENVIRONMENT_NAME_PATTERN } from "@nylorun/core/contracts";
 import matter from "gray-matter";
 const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /** Version control and operating system files, never part of a skill. */
@@ -71,12 +72,12 @@ export function loadSkillsFromDirectory(directory, diagnostics, options = {}) {
             });
             continue;
         }
-        const parsed = parseSkill(readFileSync(skillReal, "utf8"), entry.name);
-        if (!parsed) {
+        const parsed = readSkill(readFileSync(skillReal, "utf8"), entry.name);
+        if (typeof parsed === "string") {
             diagnostics.push({
                 severity: "warning",
                 code: `${prefix}.skill-skipped`,
-                message: `Skipped skill '${entry.name}' because SKILL.md is not a valid Agent Skill`,
+                message: `Skipped skill '${entry.name}' because SKILL.md ${parsed}`,
                 path: skillFile,
             });
             continue;
@@ -93,36 +94,61 @@ export function loadSkillsFromDirectory(directory, diagnostics, options = {}) {
         skills[parsed.name] = {
             name: parsed.name,
             description: parsed.description,
-            ...readFiles(parsed.name, boundary, directoryReal, diagnostics, prefix),
+            ...(parsed.secrets === undefined ? {} : { secrets: parsed.secrets }),
+            ...readFiles(`skill '${parsed.name}'`, boundary, directoryReal, diagnostics, prefix),
         };
     }
     return skills;
 }
 export function parseSkill(text, directoryName) {
+    const parsed = readSkill(text, directoryName);
+    return typeof parsed === "string" ? undefined : parsed;
+}
+const INVALID_SKILL = "is not a valid Agent Skill";
+/** The skill a SKILL.md declares, or why it declares none. */
+function readSkill(text, directoryName) {
     let parsed;
     try {
         parsed = matter(text);
     }
     catch {
-        return undefined;
+        return INVALID_SKILL;
     }
     const name = asTrimmedString(parsed.data.name);
     const description = asTrimmedString(parsed.data.description);
     if (!name || !description || description.length > 1024)
-        return undefined;
+        return INVALID_SKILL;
     if (name.length > 64 || !SKILL_NAME.test(name) || name !== directoryName)
-        return undefined;
+        return INVALID_SKILL;
+    const secrets = parsed.data.secrets;
+    if (secrets !== undefined &&
+        (!Array.isArray(secrets) ||
+            !secrets.every((item) => typeof item === "string" && ENVIRONMENT_NAME_PATTERN.test(item))))
+        return "has secrets that are not a list of environment variable names";
     return {
         name,
         description,
+        ...(secrets === undefined || secrets.length === 0
+            ? {}
+            : { secrets: [...new Set(secrets)].sort() }),
         instructions: parsed.content.replace(/^\r?\n/, ""),
     };
 }
 function asTrimmedString(value) {
     return typeof value === "string" ? value.trim() : "";
 }
-/** Every file of the skill's folder, hashed, and where to read each one's bytes. */
-function readFiles(name, boundary, directory, diagnostics, prefix) {
+/**
+ * Every file of `directory` (a runtime section's `files` entry with `from`), hashed as a skill's
+ * folder is: each by its `/`-separated path, with where to read its bytes. Version control, OS
+ * and `.env` files are left out; a symbolic link outside `boundary` (default the folder) is
+ * skipped with a diagnostic.
+ */
+export function hashFolder(directory, diagnostics, options = {}) {
+    const root = resolveSkillsRoot(directory);
+    return readFiles(`folder ${directory}`, options.boundary ?? root, root, diagnostics, options.codePrefix ?? "files");
+}
+/** Every file of the folder, hashed, and where to read each one's bytes. */
+function readFiles(label, boundary, directory, diagnostics, prefix) {
     const files = {};
     const sources = {};
     const visited = new Set();
@@ -138,7 +164,7 @@ function readFiles(name, boundary, directory, diagnostics, prefix) {
                 diagnostics.push({
                     severity: "warning",
                     code: `${prefix}.resource-denied`,
-                    message: `Denied a file of skill '${name}' outside the package: ${entry.name}`,
+                    message: `Denied a file of ${label} outside the package: ${entry.name}`,
                     path: full,
                 });
                 continue;
@@ -154,7 +180,7 @@ function readFiles(name, boundary, directory, diagnostics, prefix) {
                 continue;
             const issue = skillFilePathIssue(path);
             if (issue)
-                throw new SkillsError(`${prefix}.invalid-path`, `Skill '${name}' has a file whose path ${issue}: ${path}`);
+                throw new SkillsError(`${prefix}.invalid-path`, `${label[0].toUpperCase()}${label.slice(1)} has a file whose path ${issue}: ${path}`);
             const hash = hashFile(real);
             files[path] = hash;
             sources[hash] = { size: stats.size, read: () => readWhole(real, stats.size) };

package/dist/skills/skills.d.ts

@@ -18,13 +18,15 @@ export interface SkillsPart extends PartDeclaration {
  * ```
  *
  * Sets `skills`: each skill's name, description and files (every file of its folder, binary
- * included, by content hash). The client uploads the files the Runtime lacks when it registers
- * the agent; the Runtime adds the skill catalog and serves `load_skill` / `read_skill_resource`
- * from them.
+ * included, by content hash). A SKILL.md's frontmatter `secrets` (environment variable names)
+ * become the skill's `secrets` in the harness section when the agent's manifest is saved. The
+ * client uploads the files the Runtime lacks when it saves the agent's manifest; the Runtime adds
+ * the skill catalog and serves `load_skill` / `read_skill_resource` from them.
  */
 export declare function skills(directory: string): SkillsPart;
 /**
- * The manifest's skills and the bytes behind their files. A plugin's skills carry its label, so
- * a tool call can be traced to the plugin that brought the skill.
+ * The manifest's skills, the bytes behind their files and the secret slots their SKILL.md lists
+ * (`secrets`, the harness section's when the agent is saved). A plugin's skills carry its label,
+ * so a tool call can be traced to the plugin that brought the skill.
  */
-export declare function skillsDeclaration(listed: readonly LoadedSkill[], plugin?: PluginLabel): Required<Pick<PartDeclaration, "skills" | "skillFiles">>;
+export declare function skillsDeclaration(listed: readonly LoadedSkill[], plugin?: PluginLabel): Required<Pick<PartDeclaration, "skills" | "skillFiles">> & Pick<PartDeclaration, "skillSecrets">;

package/dist/skills/skills.js

@@ -13,9 +13,10 @@ import { loadSkillsFromDirectory, resolveSkillsRoot, } from "./load.js";
  * ```
  *
  * Sets `skills`: each skill's name, description and files (every file of its folder, binary
- * included, by content hash). The client uploads the files the Runtime lacks when it registers
- * the agent; the Runtime adds the skill catalog and serves `load_skill` / `read_skill_resource`
- * from them.
+ * included, by content hash). A SKILL.md's frontmatter `secrets` (environment variable names)
+ * become the skill's `secrets` in the harness section when the agent's manifest is saved. The
+ * client uploads the files the Runtime lacks when it saves the agent's manifest; the Runtime adds
+ * the skill catalog and serves `load_skill` / `read_skill_resource` from them.
  */
 export function skills(directory) {
     const root = resolveSkillsRoot(directory);
@@ -29,10 +30,12 @@ export function skills(directory) {
     return { id, root, ...skillsDeclaration(listed), diagnostics };
 }
 /**
- * The manifest's skills and the bytes behind their files. A plugin's skills carry its label, so
- * a tool call can be traced to the plugin that brought the skill.
+ * The manifest's skills, the bytes behind their files and the secret slots their SKILL.md lists
+ * (`secrets`, the harness section's when the agent is saved). A plugin's skills carry its label,
+ * so a tool call can be traced to the plugin that brought the skill.
  */
 export function skillsDeclaration(listed, plugin) {
+    const secrets = listed.filter((skill) => skill.secrets !== undefined).map((skill) => [skill.name, skill.secrets]);
     return {
         skills: Object.fromEntries(listed.map((skill) => [
             skill.name,
@@ -44,5 +47,6 @@ export function skillsDeclaration(listed, plugin) {
             },
         ])),
         skillFiles: Object.assign({}, ...listed.map((skill) => skill.sources)),
+        ...(secrets.length === 0 ? {} : { skillSecrets: Object.fromEntries(secrets) }),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.23.0-beta",
+  "version": "0.25.0-beta",
   "description": "Nylorun agent definitions and session client",
   "type": "module",
   "license": "Apache-2.0",
@@ -43,16 +43,16 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@nylorun/core": "0.23.0-beta",
+    "@nylorun/core": "0.25.0-beta",
     "gray-matter": "^4.0.3"
   },
   "peerDependencies": {
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.4"
   },
   "engines": {
     "node": ">=24"