@nylorun/create-agent 0.2.0-beta

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.2.0-beta
+
+### Minor Changes
+
+- 54ab304: Configure the provider and model after project installation and before development
+  starts. Add --skip-config for deferred setup and require it for noninteractive
+  creation. Retain the project with recovery instructions when setup fails or is
+  cancelled, and cancel pending prompts, authentication, and child processes on
+  shutdown.
+
+### Patch Changes
+
+- 54ab304: Group generated npm scripts by workflow and remove the redundant `dev:host` alias.
+  Use `npm run dev -- --no-studio` for headless development.
+- 54ab304: Support portable Runtime protocol version 2 while retaining legacy Studio
+  manifest support. Move the Studio CLI into Runtime: use `nylorun studio
+--agent-url <url>` instead of `nylo studio`. Applications should install Runtime
+  directly and keep Studio as a development dependency.
+
+  Retain session lists and media across development reloads, and recognize agent
+  file changes on Windows. Validate noninteractive creator startup during release
+  verification with deferred provider configuration.
+
+  Include Harness in this release so the creator does not rely on an unpublished
+  compatibility pin. Ship and verify all four packages together.
+
+- Update the tested Harness, Runtime, and Studio compatibility combination.
+
+Release notes are maintained with Changesets.

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,55 @@
+# @nylorun/create-agent
+
+```sh
+npm create @nylorun/agent@beta my-agent
+```
+
+Creates a project that directly installs Harness and Runtime, with Studio as a development dependency. The project owns its ordinary `agent/` code and composes the packages in `nylorun.config.ts`. No server or provider implementation is copied into the project.
+
+Creation installs dependencies, runs Runtime’s provider/model configuration wizard in the same terminal, then starts development. Pass `-- --no-studio` for a headless project or `-- --no-open` to suppress the browser. `nylorun configure` connects a provider without importing the agent graph.
+
+## Configuration and recovery
+
+Use `-- --skip-config` to start development without configuring a provider:
+
+```sh
+npm create @nylorun/agent@beta my-agent -- --skip-config
+```
+
+Without interactive stdin and stdout, creation requires `--skip-config` and fails
+before creating files when it is missing. `--yes` only affects installation; it
+does not skip configuration. After skipping, run `npm run configure` inside the
+project in another terminal before sending a message. Development and Studio
+start immediately; provider configuration takes effect without restarting them.
+
+If configuration fails or is cancelled, development does not start and the
+created project is retained. Resume from its directory:
+
+```sh
+cd my-agent
+npm run configure
+npm run dev
+```
+
+If installation failed, run `npm install` first. Ctrl-C exits with status 130;
+SIGTERM exits with status 143. Cancelling setup also cancels pending authentication.
+Configuration saves the provider selection and credentials; it does not make a
+model request to validate connectivity.
+
+## Maintaining examples
+
+`starter/` is the canonical project template. `compatibility.json` pins tested Harness, Runtime, and Studio versions. `examples.recipe.json` explicitly adds the eleven-agent registry, local package references, persistence/media configuration, and test dependencies.
+
+From the repository root:
+
+```sh
+npm run examples:sync
+npm install --prefix examples
+npm run examples:check
+```
+
+The renderer is shared by project creation, the isolated starter development runner, and examples synchronization. Sync owns shell files listed in `examples/.scaffold-manifest.json`; it never edits `agent/`, tests, local model selection, credentials, or `.data/`. Edit generated configuration in the recipe or template. Conflicts with manual generated-file edits fail before any writes. CI checks the rendered shell and runs examples against the current stack. Package changes can require explicit adaptations in authored code; sync does not rewrite TypeScript imports.
+
+`npm run dev:starter` from the repository root previews a fresh project using local packages, including unpublished changes. Each preview has its own retained directory and provider configuration.
+
+Repository development: [contributing](../CONTRIBUTING.md). Package publication: [releasing](../RELEASING.md).

package/compatibility.json

@@ -0,0 +1,5 @@
+{
+  "harness": "0.11.0-beta",
+  "studio": "0.4.0-beta",
+  "runtime": "0.1.1-beta"
+}

package/dist/arguments.d.ts

@@ -0,0 +1,3 @@
+import type { CreateOptions } from "./contracts.js";
+export declare const usage = "Usage: npm create @nylorun/agent@beta <directory> [--no-studio] [--no-open] [--skip-config] [--yes]";
+export declare function parse(argv: readonly string[]): CreateOptions;

package/dist/arguments.js

@@ -0,0 +1,21 @@
+export const usage = "Usage: npm create @nylorun/agent@beta <directory> [--no-studio] [--no-open] [--skip-config] [--yes]";
+export function parse(argv) {
+    const [directory, ...flags] = argv;
+    if (!directory || directory.startsWith("-"))
+        throw new Error(usage);
+    if (flags.some((flag) => ![
+        "--studio",
+        "--no-studio",
+        "--no-open",
+        "--skip-config",
+        "--yes",
+    ].includes(flag)))
+        throw new Error(usage);
+    return Object.freeze({
+        directory,
+        studio: !flags.includes("--no-studio"),
+        open: !flags.includes("--no-open"),
+        yes: flags.includes("--yes"),
+        skipConfig: flags.includes("--skip-config"),
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { mkdir, rename, rm, writeFile, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { createProject, CreationError } from "./project.js";
+import { parse, usage } from "./arguments.js";
+import { CreationCancelled, runCommand } from "./process.js";
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 1 && ["--help", "-h"].includes(argv[0])) {
+        console.log(usage);
+        return;
+    }
+    const options = parse(argv);
+    const [major, minor] = process.versions.node.split(".").map(Number);
+    if (!(major > 22 || (major === 22 && minor >= 19)))
+        throw new Error("Nylorun project creation requires Node.js 22.19 or newer.");
+    const controller = new AbortController();
+    const onInt = () => controller.abort(new CreationCancelled("SIGINT"));
+    const onTerm = () => controller.abort(new CreationCancelled("SIGTERM"));
+    process.on("SIGINT", onInt);
+    process.on("SIGTERM", onTerm);
+    try {
+        const dependencies = {
+            currentDirectory: () => process.cwd(),
+            isInteractive: () => Boolean(process.stdin.isTTY && process.stdout.isTTY),
+            log: (message) => console.log(message),
+            signal: controller.signal,
+            exists: async (path) => existsSync(path),
+            makeDirectory: async (path) => {
+                await mkdir(path, { recursive: true });
+            },
+            rename,
+            remove: async (path) => rm(path, { recursive: true, force: true }),
+            write: async (path, content) => writeFile(path, content),
+            run: (command, args, directory) => runCommand(command, args, directory, controller.signal),
+        };
+        const compatibility = JSON.parse(await readFile(join(dirname(fileURLToPath(import.meta.url)), "compatibility.json"), "utf8"));
+        await createProject(options, compatibility, dependencies);
+    }
+    finally {
+        process.removeListener("SIGINT", onInt);
+        process.removeListener("SIGTERM", onTerm);
+    }
+}
+void main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode =
+        error instanceof CreationError || error instanceof CreationCancelled
+            ? error.exitCode
+            : 1;
+});

package/dist/compatibility.json

@@ -0,0 +1,5 @@
+{
+  "harness": "0.11.0-beta",
+  "studio": "0.4.0-beta",
+  "runtime": "0.1.1-beta"
+}

package/dist/contracts.d.ts

@@ -0,0 +1,28 @@
+export type Compatibility = Readonly<{
+    harness: string;
+    studio: string;
+    runtime: string;
+}>;
+export type CreateOptions = Readonly<{
+    directory: string;
+    studio: boolean;
+    open: boolean;
+    yes: boolean;
+    skipConfig?: boolean;
+}>;
+export type Process = Readonly<{
+    status: number | null;
+    signal?: NodeJS.Signals | null;
+}>;
+export type CreatorDependencies = Readonly<{
+    currentDirectory: () => string;
+    isInteractive: () => boolean;
+    log: (message: string) => void;
+    signal?: AbortSignal;
+    exists: (path: string) => Promise<boolean>;
+    makeDirectory: (path: string) => Promise<void>;
+    rename: (from: string, to: string) => Promise<void>;
+    remove: (path: string) => Promise<void>;
+    write: (path: string, content: string) => Promise<void>;
+    run: (command: string, args: readonly string[], directory: string) => Promise<Process>;
+}>;

package/dist/contracts.js

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

package/dist/process.d.ts

@@ -0,0 +1,8 @@
+import type { Process } from "./contracts.js";
+export declare class CreationCancelled extends Error {
+    readonly signal: NodeJS.Signals;
+    readonly exitCode: number;
+    constructor(signal: NodeJS.Signals);
+}
+/** Own npm and its descendants, including authentication started by a script. */
+export declare function runCommand(command: string, args: readonly string[], directory: string, signal: AbortSignal): Promise<Process>;

package/dist/process.js

@@ -0,0 +1,102 @@
+import { spawn } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+export class CreationCancelled extends Error {
+    signal;
+    exitCode;
+    constructor(signal) {
+        super(`Creation cancelled (${signal}).`);
+        this.signal = signal;
+        this.exitCode = signal === "SIGINT" ? 130 : 143;
+    }
+}
+/**
+ * Run the npm that launched this creator. `npm create` sets npm_execpath, which
+ * avoids the Windows `.cmd` shim (Node rejects spawning it without a shell).
+ * Arguments are fixed literals, so the shell fallback carries no injection risk.
+ */
+function npmInvocation(args) {
+    const execPath = process.env.npm_execpath;
+    if (execPath && /\.[cm]?js$/u.test(execPath))
+        return {
+            command: process.execPath,
+            args: [execPath, ...args],
+            shell: false,
+        };
+    if (process.platform === "win32")
+        return { command: "npm.cmd", args: [...args], shell: true };
+    return { command: "npm", args: [...args], shell: false };
+}
+/** Own npm and its descendants, including authentication started by a script. */
+export async function runCommand(command, args, directory, signal) {
+    signal.throwIfAborted();
+    const invocation = command === "npm"
+        ? npmInvocation(args)
+        : { command, args: [...args], shell: false };
+    const child = spawn(invocation.command, invocation.args, {
+        cwd: directory,
+        stdio: "inherit",
+        detached: process.platform !== "win32",
+        shell: invocation.shell,
+    });
+    let shutdown;
+    const stop = (requested) => {
+        shutdown ??= stopTree(requested);
+        // Await cleanup below, but observe early failures while npm is still exiting.
+        void shutdown.catch(() => undefined);
+    };
+    const onAbort = () => stop(signal.reason instanceof CreationCancelled
+        ? signal.reason.signal
+        : "SIGTERM");
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted)
+        onAbort();
+    try {
+        const result = await new Promise((resolve, reject) => {
+            child.once("error", reject);
+            child.once("close", (status, endedBy) => resolve({ status, signal: endedBy }));
+        });
+        if (result.signal || result.status === 130 || result.status === 143)
+            stop(result.signal ?? (result.status === 130 ? "SIGINT" : "SIGTERM"));
+        await shutdown;
+        signal.throwIfAborted();
+        return result;
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+        await shutdown;
+    }
+    async function stopTree(requested) {
+        if (!child.pid)
+            return;
+        if (process.platform === "win32") {
+            await new Promise((resolve) => {
+                const killer = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+                killer.once("error", () => resolve());
+                killer.once("close", () => resolve());
+            });
+            return;
+        }
+        const send = (value) => {
+            try {
+                process.kill(-child.pid, value);
+                return true;
+            }
+            catch (error) {
+                if (error.code === "ESRCH")
+                    return false;
+                // EPERM on a liveness probe means the group still exists. Recheck while
+                // exiting descendants are reaped; actual signal failures still propagate.
+                if (value === 0 && error.code === "EPERM")
+                    return true;
+                throw error;
+            }
+        };
+        if (!send(requested))
+            return;
+        const deadline = Date.now() + 5000;
+        while (send(0) && Date.now() < deadline)
+            await delay(25);
+        if (send(0))
+            send("SIGKILL");
+    }
+}

package/dist/project.d.ts

@@ -0,0 +1,6 @@
+import type { Compatibility, CreateOptions, CreatorDependencies } from "./contracts.js";
+export declare class CreationError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+export declare function createProject(options: CreateOptions, compatibility: Compatibility, dependencies: CreatorDependencies): Promise<void>;

package/dist/project.js

@@ -0,0 +1,88 @@
+import { basename, dirname, isAbsolute, join, relative, resolve, } from "node:path";
+import { randomUUID } from "node:crypto";
+import { starterFiles } from "./scaffold.js";
+import { CreationCancelled } from "./process.js";
+export class CreationError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+export async function createProject(options, compatibility, dependencies) {
+    const currentDirectory = resolve(dependencies.currentDirectory());
+    const destination = resolve(currentDirectory, options.directory);
+    const pathFromCurrentDirectory = relative(currentDirectory, destination);
+    if (isAbsolute(options.directory) ||
+        pathFromCurrentDirectory === "" ||
+        pathFromCurrentDirectory === ".." ||
+        pathFromCurrentDirectory.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`))
+        throw new Error("Target directory must be a new child of the current directory.");
+    if (await dependencies.exists(destination))
+        throw new Error(`Target directory already exists: ${destination}`);
+    if (!options.skipConfig && !dependencies.isInteractive())
+        throw new Error("Provider configuration requires interactive stdin and stdout. " +
+            `To configure later, run: npm create @nylorun/agent@beta ${quote(options.directory)} -- --skip-config`);
+    dependencies.signal?.throwIfAborted();
+    const temporary = join(dirname(destination), `.${basename(destination)}-${randomUUID()}`);
+    await dependencies.makeDirectory(temporary);
+    try {
+        for (const [relative, content] of Object.entries(await starterFiles(compatibility, options.studio))) {
+            const file = join(temporary, relative);
+            await dependencies.makeDirectory(dirname(file));
+            await dependencies.write(file, content);
+            dependencies.signal?.throwIfAborted();
+        }
+        await dependencies.rename(temporary, destination);
+    }
+    catch (error) {
+        await dependencies.remove(temporary);
+        throw error;
+    }
+    dependencies.log("Installing dependencies...");
+    await stage("Installation", ["install", ...(options.yes ? ["--yes"] : [])]);
+    if (options.skipConfig) {
+        dependencies.log(`Provider configuration skipped. Configure later in another terminal:\ncd ${quote(destination)}\nnpm run configure`);
+    }
+    else {
+        dependencies.log("Configuring your provider and model...");
+        await stage("Provider configuration", ["run", "configure"]);
+    }
+    dependencies.log("Starting development...");
+    await stage("Development", [
+        "run",
+        "dev",
+        ...(options.open ? [] : ["--", "--no-open"]),
+    ]);
+    async function stage(name, args) {
+        try {
+            dependencies.signal?.throwIfAborted();
+            const result = await dependencies.run("npm", args, destination);
+            dependencies.signal?.throwIfAborted();
+            if (result.signal === "SIGINT" || result.status === 130)
+                throw new CreationCancelled("SIGINT");
+            if (result.signal === "SIGTERM" || result.status === 143)
+                throw new CreationCancelled("SIGTERM");
+            if (result.status !== 0 || result.signal)
+                throw new Error(`${name} failed.`);
+        }
+        catch (error) {
+            const cancelled = error instanceof CreationCancelled;
+            const configured = name === "Development" && !options.skipConfig;
+            const recovery = [
+                `cd ${quote(destination)}`,
+                ...(name === "Installation" ? ["npm install"] : []),
+                ...(configured ? [] : ["npm run configure"]),
+                "npm run dev",
+            ].join("\n");
+            throw new CreationError(`${cancelled ? error.message : `${name} failed.`} The generated project was kept.\n${name === "Development" ? "Restart" : "Resume"} with:\n${recovery}`, cancelled ? error.exitCode : 1);
+        }
+    }
+}
+function quote(value) {
+    if (/^[a-zA-Z0-9_./-]+$/.test(value))
+        return value;
+    return process.platform === "win32"
+        ? `"${value.replaceAll('"', '""')}"`
+        : `'${value.replaceAll("'", "'\\''")}'`;
+}

package/dist/scaffold.d.ts

@@ -0,0 +1,2 @@
+import type { Compatibility } from "./contracts.js";
+export declare function starterFiles(compatibility: Compatibility, studio: boolean): Promise<Readonly<Record<string, string>>>;

package/dist/scaffold.js

@@ -0,0 +1,40 @@
+import { readdir, readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { join, relative, sep } from "node:path";
+/** The only renderer used by creation, development, and examples synchronization. */
+/**
+ * npm never packs files named `.gitignore` and treats them as ignore rules for
+ * their directory, so the template stores them as `_gitignore`.
+ */
+function templatePath(path) {
+    return path
+        .split(sep)
+        .map((segment) => (segment === "_gitignore" ? ".gitignore" : segment))
+        .join("/");
+}
+export async function starterFiles(compatibility, studio) {
+    const root = fileURLToPath(new URL("./starter/", import.meta.url));
+    const files = {};
+    async function walk(directory) {
+        for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            const absolute = join(directory, entry.name);
+            if (entry.isDirectory())
+                await walk(absolute);
+            else
+                files[templatePath(relative(root, absolute))] = (await readFile(absolute, "utf8"))
+                    .replaceAll("{{HARNESS_VERSION}}", compatibility.harness)
+                    .replaceAll("{{RUNTIME_VERSION}}", compatibility.runtime)
+                    .replaceAll("{{STUDIO_VERSION}}", compatibility.studio);
+        }
+    }
+    await walk(root);
+    if (!("." + "gitignore" in files))
+        throw new Error("Starter template is missing its .gitignore.");
+    if (!studio) {
+        const manifest = JSON.parse(files["package.json"]);
+        delete manifest.devDependencies["@nylorun/studio"];
+        manifest.scripts.dev = "nylorun dev --no-studio";
+        files["package.json"] = JSON.stringify(manifest, null, 2) + "\n";
+    }
+    return Object.freeze(files);
+}

package/dist/starter/.env/README.md

@@ -0,0 +1,4 @@
+# Project credentials
+
+Run `npm run configure`. Provider credentials are stored in `auth.json`.
+Do not commit credentials. Optional integration environment variables belong in `integrations.env`.

package/dist/starter/.env/_gitignore

@@ -0,0 +1,3 @@
+*
+!.gitignore
+!README.md

package/dist/starter/README.md

@@ -0,0 +1,6 @@
+# My agent
+
+The creator configures a provider before starting development. For later sessions, run `npm run dev`. If setup was skipped with `--skip-config` or interrupted, run `npm run configure` first, then `npm run dev`.
+Edit agents under `agent/` and compose Runtime in `nylorun.config.ts`.
+
+`npm run dev -- --no-studio` starts without Studio. `npm run build` creates `dist/`; deploy it alongside `package.json`, installed production dependencies, and private project configuration, then run `npm start`.

package/dist/starter/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+.data/
+.env/*
+!.env/.gitignore
+!.env/README.md
+config/model.json

package/dist/starter/agent/assistant/agent.ts

@@ -0,0 +1,10 @@
+import { Agent } from "@nylorun/harness";
+import { piModel } from "@nylorun/runtime";
+
+export const assistant = Agent({
+  id: "assistant",
+  name: "Assistant",
+  instructions: ["You are helpful."],
+})
+  .with(piModel())
+  .build();

package/dist/starter/agent/registry.ts

@@ -0,0 +1,3 @@
+import { assistant } from "./assistant/agent.js";
+
+export const agents = [assistant];

package/dist/starter/nylorun.config.ts

@@ -0,0 +1,4 @@
+import { defineRuntime } from "@nylorun/runtime";
+import { agents } from "./agent/registry.js";
+
+export default defineRuntime({ agents });

package/dist/starter/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "my-nylorun-agent",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "configure": "nylorun configure",
+    "dev": "nylorun dev",
+    "inspect": "nylorun inspect",
+    "build": "nylorun build",
+    "start": "nylorun start",
+    "check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@nylorun/harness": "{{HARNESS_VERSION}}",
+    "@nylorun/runtime": "{{RUNTIME_VERSION}}",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@nylorun/studio": "{{STUDIO_VERSION}}",
+    "@types/node": "^22.18.0",
+    "typescript": "^5.9.3"
+  }
+}

package/dist/starter/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["agent/**/*.ts", "nylorun.config.ts"]
+}

package/dist/sync.d.ts

@@ -0,0 +1,17 @@
+import type { Compatibility } from "./contracts.js";
+export interface ExamplesRecipe {
+    name: string;
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    scripts: Record<string, string>;
+    configuration: string;
+}
+export declare function examplesFiles(compatibility: Compatibility, recipe: ExamplesRecipe): Promise<{
+    [k: string]: string;
+}>;
+/** Preflight the whole tree before edits. Authored paths and local state are never eligible. */
+export declare function synchronize(root: string, files: Readonly<Record<string, string>>, compatibility: Compatibility, options: {
+    check?: boolean;
+    adopt?: boolean;
+    creatorVersion: string;
+}): Promise<readonly string[]>;

package/dist/sync.js

@@ -0,0 +1,137 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { starterFiles } from "./scaffold.js";
+export async function examplesFiles(compatibility, recipe) {
+    const rendered = await starterFiles(compatibility, true);
+    const files = Object.fromEntries(Object.entries(rendered).filter(([path]) => managed(path)));
+    const manifest = JSON.parse(files["package.json"]);
+    manifest.name = recipe.name;
+    for (const field of ["dependencies", "devDependencies", "scripts"])
+        manifest[field] = { ...manifest[field], ...recipe[field] };
+    // Recipe additions belong beside the corresponding starter commands.
+    const scriptOrder = [
+        "configure",
+        "dev",
+        "inspect",
+        "studio",
+        "build",
+        "start",
+        "check",
+        "test",
+    ];
+    const rank = (name) => {
+        const index = scriptOrder.indexOf(name);
+        return index < 0 ? scriptOrder.length : index;
+    };
+    manifest.scripts = Object.fromEntries(Object.entries(manifest.scripts).sort(([left], [right]) => rank(left) - rank(right) || left.localeCompare(right)));
+    files["package.json"] = JSON.stringify(manifest, null, 2) + "\n";
+    files["nylorun.config.ts"] = recipe.configuration;
+    const tsconfig = JSON.parse(files["tsconfig.json"]);
+    tsconfig.include.push("test/**/*.ts");
+    files["tsconfig.json"] = JSON.stringify(tsconfig, null, 2) + "\n";
+    return files;
+}
+function managed(path) {
+    return (!path.startsWith("agent/") &&
+        !path.startsWith("config/") &&
+        path !== "README.md");
+}
+const manifestPath = ".scaffold-manifest.json";
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+/** Preflight the whole tree before edits. Authored paths and local state are never eligible. */
+export async function synchronize(root, files, compatibility, options) {
+    root = resolve(root);
+    async function pathFor(path) {
+        if (!path ||
+            path.includes("\\") ||
+            path.split("/").some((part) => !part || part === "." || part === "..") ||
+            !managed(path) ||
+            path.startsWith("test/") ||
+            path.startsWith("scripts/") ||
+            path.startsWith(".data/") ||
+            path.startsWith("node_modules/") ||
+            (path.startsWith(".env/") &&
+                ![".env/README.md", ".env/.gitignore"].includes(path)))
+            throw new Error(`Refusing unmanaged path: ${path}`);
+        let current = root;
+        for (const part of path.split("/")) {
+            current = join(current, part);
+            try {
+                const stat = await lstat(current);
+                if (stat.isSymbolicLink())
+                    throw new Error(`Refusing symlink: ${path}`);
+                if (current !== join(root, path) && !stat.isDirectory())
+                    throw new Error(`Cannot write ${path}: relocate the legacy .env file before syncing; its contents will not be changed.`);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        return join(root, path);
+    }
+    async function read(path) {
+        try {
+            return await readFile(await pathFor(path), "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+    }
+    const priorText = await read(manifestPath);
+    const prior = priorText
+        ? JSON.parse(priorText)
+        : undefined;
+    if (prior &&
+        (prior.version !== 1 || !prior.files || typeof prior.files !== "object"))
+        throw new Error("Invalid scaffold manifest.");
+    const hashes = Object.fromEntries(Object.keys(files)
+        .sort()
+        .map((path) => [path, hash(files[path])]));
+    const provenance = {
+        version: 1,
+        creatorVersion: options.creatorVersion,
+        compatibility,
+        templateHash: hash(JSON.stringify(hashes)),
+        files: hashes,
+    };
+    const changes = [];
+    const writes = new Map();
+    const removals = [];
+    for (const path of new Set([
+        ...Object.keys(prior?.files ?? {}),
+        ...Object.keys(files),
+    ])) {
+        const existing = await read(path);
+        const desired = files[path];
+        if (existing === desired)
+            continue;
+        changes.push(path);
+        if (!options.check &&
+            existing !== undefined &&
+            hash(existing) !== prior?.files[path] &&
+            !(options.adopt && !prior))
+            throw new Error(`Generated-file conflict: ${path}. Move the intended change into the creator template or recipe before syncing.`);
+        if (desired === undefined)
+            removals.push(path);
+        else
+            writes.set(path, desired);
+    }
+    const next = JSON.stringify(provenance, null, 2) + "\n";
+    if (priorText !== next)
+        changes.push(manifestPath);
+    if (options.check)
+        return changes;
+    for (const [path, content] of writes) {
+        const file = await pathFor(path);
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, content);
+    }
+    for (const path of removals)
+        await rm(await pathFor(path));
+    await writeFile(await pathFor(manifestPath), next);
+    return changes;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@nylorun/create-agent",
+  "version": "0.2.0-beta",
+  "description": "Create a local Nylorun Harness agent project.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nylorun/harness.git",
+    "directory": "create-agent"
+  },
+  "homepage": "https://github.com/nylorun/harness",
+  "bugs": "https://github.com/nylorun/harness/issues",
+  "bin": {
+    "create-agent": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "compatibility.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "build": "npm run clean && node ../scripts/check-typescript-version.mjs && tsc -p tsconfig.json && node scripts/copy-compatibility.mjs",
+    "check": "npm run build && npm run test:types && npm test && node scripts/check-package.mjs",
+    "test": "vitest run",
+    "test:types": "tsc -p test/tsconfig.json",
+    "examples:sync": "npm run build && node scripts/examples.mjs",
+    "examples:check": "npm run build && node scripts/examples.mjs --check",
+    "clean": "node -e \"import('node:fs').then(({rmSync})=>rmSync('dist',{recursive:true,force:true}))\"",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@nylorun/harness": "file:../harness",
+    "@nylorun/runtime": "file:../runtime",
+    "@types/node": "^22.18.0",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^4.1.11",
+    "zod": "^4.1.12"
+  }
+}