@rivet-dev/agentos-toolchain 0.0.0-nathan-agentos-package-resolution.efc374f

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 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 the 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 the 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 any 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
+
+   Copyright 2025 Rivet Gaming, Inc.
+
+   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,76 @@
+# @rivet-dev/agentos-toolchain
+
+Build toolchain for **agentOS packages** — the only sanctioned way to turn an npm
+package or a local script into a valid, self-contained agentOS package.
+
+```bash
+npx @rivet-dev/agentos-toolchain pack <npm-pkg | ./local-dir> [options]
+```
+
+## Why this lives in secure-exec
+
+**Packaging is part of secure-exec's core behavior, so the tool that produces
+packages lives here, next to the things it packages.** secure-exec owns the VM
+runtime that *runs* packages — the kernel, the VFS, the `/opt/agentos` mount, the
+`$PATH` command resolver, and the header/`binfmt` dispatch — and it owns the
+package **definitions** themselves: the generic registry software (`registry/software/*`)
+and the agent adapters (`registry/agent/*`). This toolchain is what builds those
+definitions into the on-disk package format that the runtime resolves. Its
+`header.ts` is the same `binfmt` table the sidecar enforces (`crates/sidecar`), so
+keeping it in this repo keeps the producer and the consumer of the format in one
+place.
+
+agent-os (the product layer) only *consumes* finished packages via
+`defineSoftware({ name, dir })`; it does not need to own the builder. The package
+name stays `@rivet-dev/agentos-toolchain` so the documented `npx` entrypoint is
+unchanged.
+
+## `pack`
+
+Produces `<out>/<name>/<version>/` — a package in the agentOS
+[package format](https://agentos-sdk.dev/docs/architecture/packages-and-command-resolution):
+
+The output is a **flat, self-contained package directory** — a plain npm dependency, no
+agentOS-specific manifest and no symlinks:
+
+```
+<out>/                       # the package dir itself (default ./<input-name>-package)
+├── package.json             # name, version, and the "bin" command map
+└── node_modules/            # flat, self-contained dependency closure
+```
+
+Commands are declared in `package.json` `"bin"` (command → a **real entry file**), so the
+package ships cleanly via npm. The runtime builds the `/opt/agentos/bin` symlinks itself when
+it mounts the package — they are never part of the shipped artifact.
+
+### Steps
+
+1. **Isolate** — a clean temp dir (no host pnpm/workspace bleed-through).
+2. **Install flat** — `npm install <pkg> --omit=dev` (full closure, hoisted, no scripts).
+3. **Ensure `package.json`** — `name`/`version` from the package plus a `"bin"` map (each entry
+   gets a `#!` shebang). No `agentos-package.json` — `package.json` is the only metadata.
+4. **Lay out flat** — `package.json` + `node_modules` written directly into `--out`.
+5. **Verify** — every `bin` entry has a recognized header (`#!` shebang or `\0asm`); **reject**
+   native `.node` addons (they can't run in V8) — the error names `--prune-native` as the escape.
+
+### Options
+
+| Flag | Meaning |
+|---|---|
+| `--agent <command>` | mark a `bin` command as the package's ACP entrypoint |
+| `--out <dir>` | output dir for the package itself (flat; default `./<input-name>-package`) |
+| `--prune-native` | delete unreachable native `.node` addons from the flat closure instead of failing |
+
+### Examples
+
+```bash
+# package a local CLI → ./my-tool-package/
+npx @rivet-dev/agentos-toolchain pack ./my-tool
+
+# an agent whose SDK closure carries unreachable native addons → ./pi-package/
+npx @rivet-dev/agentos-toolchain pack @agentos-software/pi --agent pi-sdk-acp --prune-native
+```
+
+The package is consumed by an agentOS host as `defineSoftware({ name, dir })` — add
+`agent: { acpEntrypoint: "<bin>" }` for an agent. The host projects it under `/opt/agentos`,
+and `createSession(name)` launches the adapter via `/opt/agentos/bin/<bin>`.

package/dist/chunk-7CUVPD4O.js

@@ -0,0 +1,272 @@
+// src/bundle.ts
+import { buildSync } from "esbuild";
+import { chmodSync, readFileSync, writeFileSync } from "fs";
+var SHEBANG = "#!/usr/bin/env node\n";
+function bundleEntry(entryFile, outFile) {
+  const source = readFileSync(entryFile, "utf8");
+  const withoutShebang = source.startsWith("#!") ? source.slice(source.indexOf("\n") + 1) : source;
+  const META_SHIM = "const __agentos_import_meta_url = require('url').pathToFileURL(__filename).href;";
+  buildSync({
+    stdin: {
+      contents: withoutShebang,
+      resolveDir: entryFile.slice(0, entryFile.lastIndexOf("/")),
+      sourcefile: entryFile,
+      loader: "js"
+    },
+    bundle: true,
+    platform: "node",
+    format: "cjs",
+    target: "node20",
+    outfile: outFile,
+    banner: { js: `${SHEBANG.trimEnd()}
+${META_SHIM}` },
+    define: { "import.meta.url": "__agentos_import_meta_url" },
+    logLevel: "silent"
+  });
+  chmodSync(outFile, 493);
+  const out = readFileSync(outFile, "utf8");
+  if (!out.startsWith(SHEBANG)) {
+    writeFileSync(outFile, `${SHEBANG}${out.replace(/^#![^\n]*\n?/, "")}`);
+    chmodSync(outFile, 493);
+  }
+}
+
+// src/header.ts
+var WASM_MAGIC = Buffer.from([0, 97, 115, 109]);
+var ELF_MAGIC = Buffer.from([127, 69, 76, 70]);
+var MACHO_MAGICS = [
+  4277009102,
+  3472551422,
+  4277009103,
+  3489328638,
+  3405691582,
+  3199925962
+];
+function detectExecutableKind(head) {
+  if (head.length >= 2 && head[0] === 35 && head[1] === 33) {
+    return "shebang";
+  }
+  if (head.length >= 4 && head.subarray(0, 4).equals(WASM_MAGIC)) {
+    return "wasm";
+  }
+  if (head.length >= 4 && head.subarray(0, 4).equals(ELF_MAGIC)) {
+    return "native-elf";
+  }
+  if (head.length >= 4) {
+    const be = head.readUInt32BE(0);
+    if (be === 3405691582 && head.length >= 8) {
+      const next = head.readUInt32BE(4);
+      if (next >= 45) return "unknown";
+    }
+    if (MACHO_MAGICS.includes(be)) return "native-macho";
+  }
+  if (head.length >= 2 && head[0] === 77 && head[1] === 90) {
+    return "native-pe";
+  }
+  return "unknown";
+}
+function isNativeKind(kind) {
+  return kind === "native-elf" || kind === "native-macho" || kind === "native-pe";
+}
+function parseShebangInterpreter(head) {
+  if (!(head.length >= 2 && head[0] === 35 && head[1] === 33)) return null;
+  const nl = head.indexOf(10);
+  const line = head.subarray(2, nl < 0 ? head.length : nl).toString("utf8");
+  const trimmed = line.replace(/^\s+/, "");
+  const interp = trimmed.split(/\s+/, 1)[0] ?? "";
+  return interp.length > 0 ? interp : null;
+}
+
+// src/pack.ts
+import { execFileSync } from "child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readFileSync as readFileSync2,
+  readSync,
+  closeSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { tmpdir } from "os";
+import { join, relative, resolve } from "path";
+var HEAD_BYTES = 256;
+function readHead(file) {
+  const fd = openSync(file, "r");
+  try {
+    const buf = Buffer.alloc(HEAD_BYTES);
+    const n = readSync(fd, buf, 0, HEAD_BYTES, 0);
+    return buf.subarray(0, n);
+  } finally {
+    closeSync(fd);
+  }
+}
+function npmInstallFlat(source, into) {
+  mkdirSync(join(into, "node_modules"), { recursive: true });
+  execFileSync(
+    "npm",
+    [
+      "install",
+      source,
+      "--omit=dev",
+      "--ignore-scripts",
+      "--no-audit",
+      "--no-fund",
+      "--no-package-lock",
+      "--install-strategy=hoisted",
+      "--prefix",
+      into
+    ],
+    { stdio: "pipe" }
+  );
+}
+function installedPackageName(source) {
+  if (existsSync(source) && statSync(source).isDirectory()) {
+    const pkg = JSON.parse(readFileSync2(join(source, "package.json"), "utf8"));
+    return pkg.name;
+  }
+  const at = source.lastIndexOf("@");
+  return at > 0 ? source.slice(0, at) : source;
+}
+function binEntries(pkgDir) {
+  const pkg = JSON.parse(readFileSync2(join(pkgDir, "package.json"), "utf8"));
+  const bin = pkg.bin;
+  if (!bin) return {};
+  if (typeof bin === "string") {
+    return { [pkg.name.replace(/^@[^/]+\//, "")]: bin };
+  }
+  return bin;
+}
+function findNativeAddons(root) {
+  const hits = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, entry.name);
+      if (entry.isDirectory()) walk(p);
+      else if (entry.isFile() && entry.name.endsWith(".node")) hits.push(p);
+    }
+  };
+  if (existsSync(root)) walk(root);
+  return hits;
+}
+function verifyPackageDir(packageDir) {
+  const pkgJsonPath = join(packageDir, "package.json");
+  if (!existsSync(pkgJsonPath)) {
+    throw new Error(`missing required package.json in ${packageDir}`);
+  }
+  let version;
+  try {
+    version = JSON.parse(readFileSync2(pkgJsonPath, "utf8")).version;
+  } catch (error) {
+    throw new Error(
+      `package.json in ${packageDir} is not valid JSON: ${String(error)}`
+    );
+  }
+  if (typeof version !== "string" || version.length === 0) {
+    throw new Error(`package.json in ${packageDir} is missing a valid "version"`);
+  }
+  const binDir = join(packageDir, "bin");
+  if (!existsSync(binDir)) {
+    throw new Error(`package has no bin/ directory: ${packageDir}`);
+  }
+  for (const entry of readdirSync(binDir)) {
+    const target = resolve(binDir, entry);
+    const kind = detectExecutableKind(readHead(target));
+    if (isNativeKind(kind)) {
+      throw new Error(
+        `bin/${entry} is a native ${kind} binary, which cannot run in agentOS`
+      );
+    }
+    if (kind === "unknown") {
+      throw new Error(
+        `bin/${entry} has no recognized header \u2014 JS/script commands need a '#!' shebang`
+      );
+    }
+  }
+  const addons = findNativeAddons(join(packageDir, "node_modules"));
+  if (addons.length > 0) {
+    throw new Error(
+      `package contains native .node addons (won't load in V8): ${addons.map((a) => relative(packageDir, a)).join(", ")}`
+    );
+  }
+}
+function pack(options) {
+  const { source, out, agent, bundle, pruneNative } = options;
+  const tmp = mkdtempSync(join(tmpdir(), "agentos-pack-"));
+  try {
+    const absSource = existsSync(source) && statSync(source).isDirectory() ? resolve(source) : source;
+    npmInstallFlat(absSource, tmp);
+    const name = installedPackageName(source);
+    const installedDir = join(tmp, "node_modules", name);
+    const pkg = JSON.parse(readFileSync2(join(installedDir, "package.json"), "utf8"));
+    const version = pkg.version;
+    const bins = binEntries(installedDir);
+    const commands = Object.keys(bins);
+    if (commands.length === 0) {
+      throw new Error(`package "${name}" declares no bin commands`);
+    }
+    if (agent && !commands.includes(agent)) {
+      throw new Error(
+        `--agent "${agent}" is not one of the package's commands: ${commands.join(", ")}`
+      );
+    }
+    const packageDir = out;
+    rmSync(packageDir, { recursive: true, force: true });
+    mkdirSync(packageDir, { recursive: true });
+    const binDir = join(packageDir, "bin");
+    mkdirSync(binDir, { recursive: true });
+    if (bundle) {
+      for (const [cmd, entryRel] of Object.entries(bins)) {
+        const entryAbs = join(installedDir, entryRel);
+        bundleEntry(entryAbs, join(binDir, cmd));
+      }
+    } else {
+      cpSync(join(tmp, "node_modules"), join(packageDir, "node_modules"), {
+        recursive: true
+      });
+      for (const [cmd, entryRel] of Object.entries(bins)) {
+        const targetAbs = join(packageDir, "node_modules", name, entryRel);
+        symlinkSync(relative(binDir, targetAbs), join(binDir, cmd));
+      }
+      if (pruneNative) {
+        const addons = findNativeAddons(join(packageDir, "node_modules"));
+        for (const addon of addons) {
+          rmSync(addon, { force: true });
+        }
+        if (addons.length > 0) {
+          console.warn(
+            `[agentos-toolchain] pruned ${addons.length} native .node addon(s) from ${name} (--prune-native); they must be unreachable on the V8 code path`
+          );
+        }
+      }
+    }
+    const binMap = {};
+    for (const cmd of commands) {
+      binMap[cmd] = `bin/${cmd}`;
+    }
+    writeFileSync2(
+      join(packageDir, "package.json"),
+      `${JSON.stringify({ name, version, bin: binMap }, null, 2)}
+`
+    );
+    verifyPackageDir(packageDir);
+    return { name, version, packageDir, commands };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+export {
+  bundleEntry,
+  detectExecutableKind,
+  isNativeKind,
+  parseShebangInterpreter,
+  verifyPackageDir,
+  pack
+};