@sapiom/agent-studio 0.0.1

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @sapiom/agent-studio

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sapiom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# Agent Studio
+
+Agent Studio is a local workspace for building, testing, deploying, and running
+Sapiom agents with your own coding agent.
+
+```bash
+npx @sapiom/agent-studio@latest [dir]
+```
+
+The optional directory defaults to the current working directory. Every Agent
+Studio launch flag is passed through unchanged, including `--port`, `--login`,
+`--no-open`, `--no-auth`, `--no-telemetry`, `--no-session`, and `--state-root`.
+
+This package is the branded public launcher. It delegates to an exact,
+release-tested version of the `@sapiom/harness` implementation package; it does
+not contain a second copy of the application. The supported direct command
+continues to work:
+
+```bash
+npx @sapiom/harness@latest [dir]
+```
+
+Agent Studio requires Node.js 20 or newer and Claude Code or Codex on `PATH`.

package/bin/agent-studio.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import { AgentStudioLaunchError, launchAgentStudio } from "../lib/launcher.mjs";
+
+try {
+  await launchAgentStudio();
+} catch (error) {
+  if (error instanceof AgentStudioLaunchError) {
+    console.error(
+      `Agent Studio failed to launch [${error.code}]: ${error.message}`,
+    );
+    if (error.hint) console.error(error.hint);
+  } else {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Agent Studio failed to launch: ${message}`);
+  }
+  process.exitCode = 1;
+}

package/lib/launcher.mjs

@@ -0,0 +1,158 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const requireFromLauncher = createRequire(import.meta.url);
+
+export class AgentStudioLaunchError extends Error {
+  constructor({ code, message, hint, cause }) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = "AgentStudioLaunchError";
+    this.code = code;
+    this.hint = hint;
+  }
+}
+
+function defaultResolvePackageJson() {
+  return requireFromLauncher.resolve("@sapiom/harness/package.json");
+}
+
+/** Resolve the implementation bin without importing or duplicating Harness. */
+export function resolveHarnessBin({
+  resolvePackageJson = defaultResolvePackageJson,
+  readFile = readFileSync,
+  fileExists = existsSync,
+} = {}) {
+  let packageJsonPath;
+  try {
+    packageJsonPath = resolvePackageJson();
+  } catch (cause) {
+    throw new AgentStudioLaunchError({
+      code: "HARNESS_NOT_INSTALLED",
+      message:
+        "The @sapiom/harness implementation package could not be resolved.",
+      hint: "Reinstall with: npx --yes @sapiom/agent-studio@latest",
+      cause,
+    });
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(readFile(packageJsonPath, "utf8"));
+  } catch (cause) {
+    throw new AgentStudioLaunchError({
+      code: "HARNESS_MANIFEST_INVALID",
+      message: "The @sapiom/harness package manifest could not be read.",
+      hint: "Reinstall with: npx --yes @sapiom/agent-studio@latest",
+      cause,
+    });
+  }
+
+  const binEntry = manifest?.bin?.["sapiom-harness"];
+  if (typeof binEntry !== "string" || binEntry.length === 0) {
+    throw new AgentStudioLaunchError({
+      code: "HARNESS_BIN_NOT_FOUND",
+      message: "The @sapiom/harness manifest has no sapiom-harness bin entry.",
+      hint: "Reinstall with: npx --yes @sapiom/agent-studio@latest",
+    });
+  }
+
+  const binPath = path.resolve(path.dirname(packageJsonPath), binEntry);
+  if (!fileExists(binPath)) {
+    throw new AgentStudioLaunchError({
+      code: "HARNESS_BIN_NOT_FOUND",
+      message: `The sapiom-harness bin was not found at ${binPath}.`,
+      hint: "Reinstall with: npx --yes @sapiom/agent-studio@latest",
+    });
+  }
+
+  return binPath;
+}
+
+/** Convert child signal termination to the shell's conventional exit status. */
+export function signalExitCode(signal) {
+  const numbers = {
+    SIGHUP: 1,
+    SIGINT: 2,
+    SIGQUIT: 3,
+    SIGKILL: 9,
+    SIGTERM: 15,
+  };
+  return 128 + (numbers[signal] ?? 0);
+}
+
+/**
+ * Launch Harness as an inherited child process.
+ *
+ * SIGINT is deliberately not forwarded: an interactive terminal delivers
+ * Ctrl-C to both processes in the foreground group, so forwarding it would
+ * signal Harness twice. SIGTERM and SIGHUP do need explicit forwarding.
+ */
+export async function launchAgentStudio({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  env = process.env,
+  execPath = process.execPath,
+  processRef = process,
+  spawn = nodeSpawn,
+  resolver,
+} = {}) {
+  const harnessBin = resolveHarnessBin(resolver);
+
+  await new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(execPath, [harnessBin, ...argv], {
+        cwd,
+        env,
+        stdio: "inherit",
+      });
+    } catch (cause) {
+      reject(
+        new AgentStudioLaunchError({
+          code: "HARNESS_SPAWN_FAILED",
+          message: `Could not start sapiom-harness: ${cause instanceof Error ? cause.message : String(cause)}`,
+          cause,
+        }),
+      );
+      return;
+    }
+
+    let settled = false;
+    const forwardSigterm = () => child.kill("SIGTERM");
+    const forwardSighup = () => child.kill("SIGHUP");
+    const cleanup = () => {
+      processRef.off("SIGTERM", forwardSigterm);
+      processRef.off("SIGHUP", forwardSighup);
+    };
+
+    processRef.on("SIGTERM", forwardSigterm);
+    processRef.on("SIGHUP", forwardSighup);
+
+    child.once("error", (cause) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(
+        new AgentStudioLaunchError({
+          code: "HARNESS_SPAWN_FAILED",
+          message: `Could not start sapiom-harness: ${cause.message}`,
+          cause,
+        }),
+      );
+    });
+
+    child.once("close", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (signal) {
+        processRef.exitCode = signalExitCode(signal);
+      } else if (code !== null && code !== 0) {
+        processRef.exitCode = code;
+      }
+      resolve();
+    });
+  });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@sapiom/agent-studio",
+  "version": "0.0.1",
+  "description": "Agent Studio — build, test, deploy, and run Sapiom agents with your coding agent in a local workspace.",
+  "keywords": [
+    "sapiom",
+    "agent-studio",
+    "claude",
+    "codex",
+    "agents"
+  ],
+  "homepage": "https://github.com/sapiom/sapiom-js/tree/main/packages/agent-studio#readme",
+  "bugs": {
+    "url": "https://github.com/sapiom/sapiom-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sapiom/sapiom-js.git",
+    "directory": "packages/agent-studio"
+  },
+  "license": "MIT",
+  "author": "Sapiom",
+  "type": "module",
+  "bin": {
+    "agent-studio": "./bin/agent-studio.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@sapiom/harness": "0.2.6"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node --check bin/agent-studio.mjs && node --check lib/launcher.mjs",
+    "test": "node --test test/*.test.mjs"
+  }
+}