@nylorun/runtime 0.1.1-beta

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.1.1-beta
+
+### Patch 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.
+- 54ab304: Add `--host` and `--allowed-hosts` to `nylorun dev` and `nylorun start`, with
+  `HOST` and `ALLOWED_HOSTS` environment equivalents. Loopback binds now answer only
+  to their own address on the chosen port, so local development needs no setup on
+  any port while DNS-rebinding pages are rejected. Publish with `--host 0.0.0.0` or
+  list proxy host names to deploy on your own servers.
+- 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.
+
+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,44 @@
+# @nylorun/runtime
+
+Portable agent hosting, pi-ai model providers, and the `nylorun` CLI. Runtime has no Harness dependency. Studio is loaded from the application only when requested.
+
+```ts
+import { defineRuntime } from "@nylorun/runtime";
+import { agents } from "./agent/registry.js";
+export default defineRuntime({ agents });
+```
+
+Applications install their engine and Runtime directly, with Studio as a development dependency. An agent may bind Runtime's `piModel()` through its engine's model interface. `piModel({ media })` uses the explicitly supplied media adapter to resolve opaque image references. It never fetches arbitrary media URLs.
+
+## Commands
+
+Run from the directory containing `nylorun.config.ts`:
+
+- `nylorun dev [--no-studio] [--no-open] [--port 4111] [--host 127.0.0.1] [--allowed-hosts a,b]`
+- `nylorun studio --agent-url http://127.0.0.1:4111 [--port 3000] [--no-open]`
+- `nylorun configure`
+- `nylorun inspect`
+- `nylorun build`
+- `nylorun start [--port 4111] [--host 127.0.0.1] [--allowed-hosts a,b]`
+
+`PORT`, `HOST` and `ALLOWED_HOSTS` environment variables supply the same settings. By default the host binds to loopback and answers only to `localhost`, `127.0.0.1` and `[::1]` on the chosen port, so changing `--port` needs no other setup and Studio connects to whatever address is printed. To publish, bind with `--host 0.0.0.0` (every Host header is then served) or keep the loopback bind behind a reverse proxy and list the public names in `--allowed-hosts`; `*` accepts any Host header. Development retains existing sessions across reloads; new sessions use the latest definitions. A failed reload leaves the previous runtime active. Studio attachment does not start or own the remote runtime.
+
+Build emits `dist/nylorun.config.js` and application assets under `dist/agent/`. Deploy `dist/`, your package manifest and lockfile, installed production dependencies, and private configuration. Production startup does not import Studio. Use `projectAsset("agent/skills/catalog")` for assets that must resolve in source and built deployments.
+
+## Configuration and adapters
+
+The default host uses in-memory history and text input. Add `persistence: localJsonl()` and `media: localMedia()` explicitly for local storage under `.data/sessions` and `.data/media`. Share the same media adapter with `piModel({ media })` and domain tools. Persistence preserves history across restarts; archived sessions cannot resume execution and require a new conversation.
+
+The creator runs `nylorun configure` after installation and before development unless `--skip-config` is passed. Standalone configuration also supports scripted input. EOF fails setup; Ctrl-C/SIGTERM cancels prompts and authentication with exit status 130/143. A cancelled setup does not proceed to development.
+
+`nylorun configure` stores provider credentials in `.env/auth.json` and selection in `config/model.json`. Agents can be imported before setup; provider authentication is resolved when the model is called. Optional integration environment variables are loaded from `.env/integrations.env`. Existing flat `.env` files must be relocated before creating the vault; never commit credentials. Image-editing and external coding integrations may use their own credentials independently.
+
+## Portable contracts
+
+`RuntimeAgent` supplies `id`, `name`, a matching `manifest`, and `run({ id })`. Its session supplies `input`, `stream`, `observe`, and `stop`. An input handle's `completed` promise settles after that input's execution or pause, with ordered lifecycle events and a status. Runtime uses completion events for terminal output and interactions, and observation events for optional diagnostics. Engines need not emit model/tool diagnostics or middleware metadata. Runtime records input before execution and flushes persistence before returning an HTTP reply. `stop()` releases session resources; optional agent `close()` runs after session shutdown. Shutdown is idempotent.
+
+`RuntimeModelAdapter` accepts ordered prompt items, tools, model controls, opaque media references, and an abort signal, returning portable text/reasoning/tool-call outputs. It has no engine import. Integration tests in the creator check assignment in both directions with Harness without casts. Runtime's own tests use an independent engine.
+
+Discovery and manifest documents use protocol version 2. The agent's manifest is under `manifest`; no engine-branded envelope is required. Existing agent-scoped HTTP endpoint paths remain unchanged. Studio also understands legacy version-1 `harness.manifest` documents.
+
+Repository development: [contributing](../CONTRIBUTING.md). Package publication: [releasing](../RELEASING.md).

package/dist/adapters/journal.d.ts

@@ -0,0 +1,35 @@
+export type CanonicalEvent = Readonly<{
+    session: string;
+    seq: number;
+    ts: string;
+    type: string;
+    payload: Record<string, unknown>;
+}>;
+export type SessionSummary = Readonly<{
+    session: string;
+    title?: string;
+    status: "idle" | "waiting";
+    startedAt: number;
+    endedAt?: number;
+}>;
+/** Explicit local-only JSONL persistence. Raw provider payloads never enter this service. */
+export declare class JsonlJournal {
+    private readonly root;
+    private readonly secrets;
+    constructor(root: string, secrets: readonly string[]);
+    append(agent: string, event: CanonicalEvent): Promise<void>;
+    events(agent: string, session: string): Promise<readonly CanonicalEvent[]>;
+    list(agent: string): Promise<readonly SessionSummary[]>;
+    private file;
+}
+export declare function scrub(value: unknown, secrets: readonly string[]): unknown;
+export interface RuntimePersistence {
+    append(agent: string, event: CanonicalEvent): Promise<void>;
+    events(agent: string, session: string): Promise<readonly CanonicalEvent[]>;
+    list(agent: string): Promise<readonly SessionSummary[]>;
+}
+export declare function localJsonl(options?: {
+    root?: string;
+    secrets?: readonly string[];
+}): RuntimePersistence;
+export declare function memoryHistory(): RuntimePersistence;

package/dist/adapters/journal.js

@@ -0,0 +1,130 @@
+import { appendFile, mkdir, readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+/** Explicit local-only JSONL persistence. Raw provider payloads never enter this service. */
+export class JsonlJournal {
+    root;
+    secrets;
+    constructor(root, secrets) {
+        this.root = root;
+        this.secrets = secrets;
+    }
+    async append(agent, event) {
+        const file = this.file(agent, event.session);
+        await mkdir(join(this.root, agent, event.session), { recursive: true });
+        await appendFile(file, `${JSON.stringify(scrub(event, this.secrets))}\n`);
+    }
+    async events(agent, session) {
+        try {
+            return Object.freeze((await readFile(this.file(agent, session), "utf8"))
+                .split("\n")
+                .filter(Boolean)
+                .flatMap((line) => {
+                try {
+                    return [JSON.parse(line)];
+                }
+                catch {
+                    return [];
+                }
+            }));
+        }
+        catch {
+            return Object.freeze([]);
+        }
+    }
+    async list(agent) {
+        try {
+            const ids = await readdir(join(this.root, agent));
+            const summaries = await Promise.all(ids.map(async (session) => {
+                const events = await this.events(agent, session);
+                const final = events.findLast((event) => event.type === "final");
+                const title = sessionTitle(events);
+                return {
+                    session,
+                    ...(title === undefined ? {} : { title }),
+                    status: sessionStatus(events),
+                    startedAt: events[0] ? Date.parse(events[0].ts) : 0,
+                    ...(final === undefined ? {} : { endedAt: Date.parse(final.ts) }),
+                };
+            }));
+            return Object.freeze(summaries.sort((a, b) => b.startedAt - a.startedAt));
+        }
+        catch {
+            return Object.freeze([]);
+        }
+    }
+    file(agent, session) {
+        return join(this.root, safe(agent), safe(session), "events.jsonl");
+    }
+}
+function sessionTitle(events) {
+    for (const event of events) {
+        if (event.type !== "session.run.started" ||
+            typeof event.payload.input !== "string")
+            continue;
+        const title = event.payload.input.replace(/\s+/gu, " ").trim();
+        if (title)
+            return title;
+    }
+    return undefined;
+}
+function sessionStatus(events) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event.type === "final")
+            return "idle";
+        if (event.type === "interaction.required")
+            return "waiting";
+        if (event.type === "session.run.started" &&
+            typeof event.payload.approved === "boolean")
+            return "idle";
+    }
+    return "idle";
+}
+function safe(value) {
+    if (value === "." || value === ".." || !/^[a-zA-Z0-9._-]+$/u.test(value)) {
+        throw new Error("Refusing a path-shaped ID.");
+    }
+    return value;
+}
+export function scrub(value, secrets) {
+    if (typeof value === "string")
+        return secrets.reduce((text, secret) => secret.length >= 8 ? text.split(secret).join("[redacted]") : text, value.replace(/data:image\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+/giu, "[inline image data redacted]"));
+    if (Array.isArray(value))
+        return value.map((item) => scrub(item, secrets));
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            /^(authorization|api[_-]?key|(?:access|refresh|id|auth)[_-]?token|token|secret|password|cookie|credentials?)$/iu.test(key)
+                ? "[redacted]"
+                : scrub(item, secrets),
+        ]));
+    return value;
+}
+export function localJsonl(options = {}) {
+    return new JsonlJournal(options.root ?? join(process.cwd(), ".data", "sessions"), options.secrets ?? []);
+}
+export function memoryHistory() {
+    const agents = new Map();
+    return {
+        async append(agent, event) {
+            const sessions = agents.get(agent) ?? new Map();
+            agents.set(agent, sessions);
+            const events = sessions.get(event.session) ?? [];
+            events.push(event);
+            sessions.set(event.session, events);
+        },
+        async events(agent, session) {
+            return agents.get(agent)?.get(session) ?? [];
+        },
+        async list(agent) {
+            return [...(agents.get(agent) ?? [])]
+                .map(([session, events]) => ({
+                session,
+                title: sessionTitle(events),
+                status: sessionStatus(events),
+                startedAt: Date.parse(events[0].ts),
+            }))
+                .sort((a, b) => b.startedAt - a.startedAt);
+        },
+    };
+}

package/dist/adapters/media.d.ts

@@ -0,0 +1,40 @@
+export declare const IMAGE_MEDIA_TYPES: readonly string[];
+export declare const MAX_IMAGE_BYTES: number;
+export interface MediaAsset {
+    readonly id: string;
+    readonly mediaType: string;
+    readonly bytes: number;
+    readonly kind: "input" | "generated";
+}
+/** Opaque reference retained by Harness and resolved by the configured media adapter. */
+export interface MediaReference {
+    readonly agentId: string;
+    readonly assetId: string;
+}
+/** Explicit local asset store; agents receive only opaque references. */
+export declare class MediaStore {
+    private readonly root;
+    constructor(root: string);
+    saveInput(agentId: string, sessionId: string, mediaType: string, base64: string): Promise<MediaAsset>;
+    saveGenerated(agentId: string, sessionId: string, mediaType: string, bytes: Uint8Array): Promise<MediaAsset>;
+    dataUrl(reference: MediaReference, sessionId: string): Promise<{
+        readonly asset: MediaAsset;
+        readonly url: string;
+    } | undefined>;
+    latestInput(agentId: string, sessionId: string): Promise<MediaAsset | undefined>;
+    read(agentId: string, sessionId: string, assetId: string): Promise<{
+        asset: MediaAsset;
+        bytes: Uint8Array;
+    } | undefined>;
+    private save;
+    private readMetadata;
+    private directory;
+}
+/** Decode one canonical base64 image before it is persisted or sent to a provider. */
+export declare function decodeImageBase64(mediaType: string, base64: string): Uint8Array;
+/** Verify the asserted media type and lightweight file signature for a supported image. */
+export declare function validateImageBytes(mediaType: string, bytes: Uint8Array): void;
+export declare function localMedia(options?: {
+    root?: string;
+}): MediaStore;
+export type RuntimeMedia = Pick<MediaStore, "saveInput" | "saveGenerated" | "dataUrl" | "latestInput" | "read">;

package/dist/adapters/media.js

@@ -0,0 +1,161 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+export const IMAGE_MEDIA_TYPES = Object.freeze([
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+]);
+export const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+/** Explicit local asset store; agents receive only opaque references. */
+export class MediaStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    async saveInput(agentId, sessionId, mediaType, base64) {
+        const bytes = decodeImageBase64(mediaType, base64);
+        return this.save(agentId, sessionId, "input", mediaType, bytes);
+    }
+    async saveGenerated(agentId, sessionId, mediaType, bytes) {
+        validateImageBytes(mediaType, bytes);
+        return this.save(agentId, sessionId, "generated", mediaType, bytes);
+    }
+    async dataUrl(reference, sessionId) {
+        const stored = await this.read(reference.agentId, sessionId, reference.assetId);
+        if (!stored)
+            return undefined;
+        return Object.freeze({
+            asset: stored.asset,
+            url: `data:${stored.asset.mediaType};base64,${Buffer.from(stored.bytes).toString("base64")}`,
+        });
+    }
+    async latestInput(agentId, sessionId) {
+        const directory = this.directory(agentId, sessionId);
+        try {
+            const metadata = await Promise.all((await readdir(directory))
+                .filter((name) => name.endsWith(".json"))
+                .map(async (name) => this.readMetadata(directory, name)));
+            return metadata
+                .filter((entry) => entry?.kind === "input")
+                .sort((left, right) => right.createdAt - left.createdAt)[0];
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async read(agentId, sessionId, assetId) {
+        if (!safe(agentId) || !safe(sessionId) || !safe(assetId))
+            return undefined;
+        const directory = this.directory(agentId, sessionId);
+        const metadata = await this.readMetadata(directory, `${assetId}.json`);
+        if (!metadata)
+            return undefined;
+        try {
+            return {
+                asset: metadata,
+                bytes: await readFile(join(directory, `${assetId}.bin`)),
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async save(agentId, sessionId, kind, mediaType, bytes) {
+        if (!safe(agentId) || !safe(sessionId))
+            throw new Error("Invalid media asset scope.");
+        const directory = this.directory(agentId, sessionId);
+        const asset = {
+            id: randomUUID(),
+            mediaType,
+            bytes: bytes.byteLength,
+            kind,
+            createdAt: Date.now(),
+        };
+        await mkdir(directory, { recursive: true });
+        await writeFile(join(directory, `${asset.id}.bin`), bytes);
+        await writeFile(join(directory, `${asset.id}.json`), JSON.stringify(asset));
+        return omitCreatedAt(asset);
+    }
+    async readMetadata(directory, name) {
+        try {
+            const value = JSON.parse(await readFile(join(directory, name), "utf8"));
+            return validAsset(value) ? value : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    directory(agentId, sessionId) {
+        return join(this.root, agentId, sessionId);
+    }
+}
+/** Decode one canonical base64 image before it is persisted or sent to a provider. */
+export function decodeImageBase64(mediaType, base64) {
+    if (!IMAGE_MEDIA_TYPES.includes(mediaType))
+        throw new Error("Only JPEG, PNG, and WebP images are supported.");
+    if (typeof base64 !== "string" || base64 === "")
+        throw new Error("Image data is required.");
+    if (base64.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/u.test(base64))
+        throw new Error("Image data must be canonical base64.");
+    const bytes = Buffer.from(base64, "base64");
+    if (bytes.toString("base64") !== base64)
+        throw new Error("Image data must be canonical base64.");
+    validateImageBytes(mediaType, bytes);
+    return bytes;
+}
+/** Verify the asserted media type and lightweight file signature for a supported image. */
+export function validateImageBytes(mediaType, bytes) {
+    if (!IMAGE_MEDIA_TYPES.includes(mediaType))
+        throw new Error("Only JPEG, PNG, and WebP images are supported.");
+    if (bytes.byteLength === 0 || bytes.byteLength > MAX_IMAGE_BYTES)
+        throw new Error("Images must be no larger than 8 MiB.");
+    const signature = mediaType === "image/jpeg"
+        ? bytes.byteLength >= 3 &&
+            bytes[0] === 0xff &&
+            bytes[1] === 0xd8 &&
+            bytes[2] === 0xff
+        : mediaType === "image/png"
+            ? bytes.byteLength >= 8 &&
+                bytes[0] === 0x89 &&
+                bytes[1] === 0x50 &&
+                bytes[2] === 0x4e &&
+                bytes[3] === 0x47 &&
+                bytes[4] === 0x0d &&
+                bytes[5] === 0x0a &&
+                bytes[6] === 0x1a &&
+                bytes[7] === 0x0a
+            : bytes.byteLength >= 12 &&
+                bytes[0] === 0x52 &&
+                bytes[1] === 0x49 &&
+                bytes[2] === 0x46 &&
+                bytes[3] === 0x46 &&
+                bytes[8] === 0x57 &&
+                bytes[9] === 0x45 &&
+                bytes[10] === 0x42 &&
+                bytes[11] === 0x50;
+    if (!signature)
+        throw new Error(`Image bytes do not match ${mediaType}.`);
+}
+function validAsset(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const asset = value;
+    return (typeof asset.id === "string" &&
+        safe(asset.id) &&
+        typeof asset.mediaType === "string" &&
+        IMAGE_MEDIA_TYPES.includes(asset.mediaType) &&
+        typeof asset.bytes === "number" &&
+        (asset.kind === "input" || asset.kind === "generated") &&
+        typeof asset.createdAt === "number");
+}
+function omitCreatedAt(asset) {
+    const { createdAt: _createdAt, ...result } = asset;
+    return Object.freeze(result);
+}
+function safe(value) {
+    return value !== "." && value !== ".." && /^[a-zA-Z0-9._-]+$/u.test(value);
+}
+export function localMedia(options = {}) {
+    return new MediaStore(options.root ?? join(process.cwd(), ".data", "media"));
+}

package/dist/assets.d.ts

@@ -0,0 +1,2 @@
+/** Resolve authored catalogs and subprocess assets in source or a built application. */
+export declare function projectAsset(path: string): string;

package/dist/assets.js

@@ -0,0 +1,10 @@
+import { existsSync } from "node:fs";
+import { resolve, relative } from "node:path";
+/** Resolve authored catalogs and subprocess assets in source or a built application. */
+export function projectAsset(path) {
+    const root = process.cwd();
+    const source = resolve(root, path);
+    if (relative(root, source).startsWith(".."))
+        throw new Error("Asset must be inside the project.");
+    return existsSync(source) ? source : resolve(root, "dist", path);
+}

package/dist/cli.d.ts

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