@codyswann/lisa 2.322.0 → 2.322.2

package/plugins/src/base/skills/lisa-remote-dispatch/scripts/dispatch.mjs

@@ -21,14 +21,53 @@
 
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
 /** Surfaces this dispatcher knows how to reach. `local` means "do not dispatch". */
-export const EXECUTION_ENVS = new Set(["local", "codex-cloud"]);
+export const EXECUTION_ENVS = new Set(["local", "codex-cloud", "claude-web"]);
+
+/**
+ * What each surface must have recorded before anything may dispatch to it.
+ *
+ * Not uniform, because the two surfaces do not bind the same way. A Codex Cloud
+ * environment is bound to one repository, so naming both is what proves the
+ * environment is the right one. A Claude cloud environment binds no repository
+ * at all — it is account-scoped configuration and the repository arrives per
+ * session — so its durable handle is the routine that dispatch fires.
+ */
+const SURFACE_PRECONDITIONS = {
+  "codex-cloud": ["environmentId", "repository"],
+  "claude-web": ["routineId", "fireUrl"],
+};
+
+/**
+ * The beta this endpoint ships under.
+ *
+ * Dated and rotating: the two most recent previous versions keep working, so a
+ * bump here is a migration with a window rather than a break. Stated once so
+ * there is a single place to move it.
+ */
+const ROUTINE_BETA = "experimental-cc-routine-2026-04-01";
+
+/**
+ * How long to wait for the routine to accept the dispatch.
+ *
+ * `fetch` has no timeout of its own, so a routine endpoint that accepts the
+ * connection and then says nothing leaves dispatch waiting forever — the one
+ * failure mode that never reaches the error path below and never reaches the
+ * operator either. Generous, because the endpoint only has to *accept* the
+ * dispatch: the session's own work happens long after this call returns, so
+ * this bounds a handshake rather than a run.
+ */
+const FIRE_TIMEOUT_MS = 30_000;
 
 /** Where dispatched work is recorded so a later session can find it. */
 const LEDGER = join(".lisa", "remote-dispatch.json");
 
+/** This file's directory, for locating the sibling secrets skill. */
+const HERE = dirname(fileURLToPath(import.meta.url));
+
 /**
  * Split `key=value` parameters from the rest of an invocation.
  *
@@ -101,9 +140,11 @@ export function readSurfaceConfig(surface, cwd = process.cwd()) {
  * @param {string} surface Execution surface.
  */
 export function assertPreconditions(block, surface) {
-  const missing = [];
-  if (!block.environmentId) missing.push("environmentId");
-  if (!block.repository) missing.push("repository");
+  const required = SURFACE_PRECONDITIONS[surface] ?? [
+    "environmentId",
+    "repository",
+  ];
+  const missing = required.filter(field => !block[field]);
   if (missing.length) {
     throw new Error(
       `remoteEnv.surfaces["${surface}"] is missing: ${missing.join(", ")}.\n` +
@@ -230,7 +271,152 @@ export function splitSkillFlag(argv) {
   return { skill, raw: rest.join(" ") };
 }
 
-function main() {
+/**
+ * Read the response a routine returns when it accepts a dispatch.
+ *
+ * Kept separate from the request so the shape can be exercised against a
+ * recorded body. The identifier is a field here rather than something scraped
+ * out of console output, which is the one respect in which this surface is
+ * easier to reconcile than the other.
+ * @param {string} body Raw response body.
+ * @returns {{sessionId: string, url: string}} The accepted session.
+ */
+export function readFireResponse(body) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw new Error(
+      `routine returned a body that is not JSON:\n${String(body).slice(0, 400)}`
+    );
+  }
+  const sessionId = parsed.claude_code_session_id;
+  const url = parsed.claude_code_session_url;
+  if (!sessionId) {
+    throw new Error(
+      `routine accepted the request but returned no session identifier.\n` +
+        `${JSON.stringify(parsed).slice(0, 400)}\n` +
+        `Refusing to report success: without the identifier nothing can ` +
+        `reconcile this run, and a retry would duplicate it.`
+    );
+  }
+  return { sessionId, url: url ?? "" };
+}
+
+/**
+ * Fire a routine and record the session it created.
+ *
+ * The payload is deliberately the work item and nothing else. It arrives on the
+ * far side wrapped in a block the platform marks as untrusted data, and a
+ * routine acts on it only because its saved prompt says to — which is the
+ * boundary this plan wanted anyway, enforced by the platform rather than by
+ * convention. Nothing here can widen the remote run's authority.
+ *
+ * The bearer token is resolved through the secrets chokepoint at the moment of
+ * use and never stored in configuration.
+ * Its three side effects — resolving a credential, making a request, writing the
+ * ledger — are all injectable, so the accept and refuse paths can be exercised
+ * without a token, a network, or a write into the working repository.
+ * @param {object} block Surface configuration.
+ * @param {string} prompt The thin skill invocation.
+ * @param {string} payload The caller's original payload, for the record.
+ * @param {{post?: Function, getToken?: Function, cwd?: string}} [options] Seams for tests.
+ * @returns {Promise<{sessionId: string, url: string}>} The accepted session.
+ */
+export async function dispatchClaudeWeb(block, prompt, payload, options = {}) {
+  const {
+    post = fetch,
+    getToken = resolveBearerToken,
+    cwd = process.cwd(),
+  } = options;
+  const token = getToken(block);
+  let response;
+  try {
+    response = await post(block.fireUrl, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${token}`,
+        "anthropic-beta": ROUTINE_BETA,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ text: prompt }),
+      signal: AbortSignal.timeout(FIRE_TIMEOUT_MS),
+    });
+  } catch (err) {
+    // A timeout arrives here as an abort rather than a network error, and
+    // "could not reach" is the true and useful thing to say about both. It is
+    // named separately so the operator can tell a silent endpoint from a
+    // refused connection, since only one of those is worth retrying.
+    const reason =
+      err.name === "TimeoutError"
+        ? `no response within ${FIRE_TIMEOUT_MS / 1000}s`
+        : err.message;
+    throw new Error(`could not reach the routine endpoint: ${reason}`);
+  }
+
+  const body = await response.text();
+  if (!response.ok) {
+    // The token is the usual cause and the usual thing to leak, so the message
+    // names the status and the routine rather than echoing the request.
+    throw new Error(
+      `routine ${block.routineId} refused the dispatch (HTTP ${response.status}).\n` +
+        `${body.slice(0, 400)}\n` +
+        `A 401 means the bearer token is wrong, revoked, or regenerated.`
+    );
+  }
+
+  const { sessionId, url } = readFireResponse(body);
+  record(
+    {
+      taskId: sessionId,
+      surface: "claude-web",
+      routineId: block.routineId,
+      sessionUrl: url,
+      prompt,
+      payload,
+      dispatchedAt: new Date().toISOString(),
+    },
+    cwd
+  );
+  return { sessionId, url };
+}
+
+/**
+ * Resolve the dispatcher's own credential through the secrets chokepoint.
+ *
+ * Never read from configuration: the token authorises starting work on someone
+ * else's infrastructure, and it can be regenerated and revoked, so it belongs
+ * in the credential manager and in `secrets.rotating` alongside it.
+ * @param {object} block Surface configuration.
+ * @returns {string} The bearer token.
+ */
+function resolveBearerToken(block) {
+  const name = block.tokenKey ?? "CLAUDE_ROUTINE_TOKEN";
+  const resolver = resolve(
+    HERE,
+    "..",
+    "..",
+    "lisa-secrets-access",
+    "scripts",
+    "resolve-secret.mjs"
+  );
+  try {
+    return execFileSync("node", [resolver, "get", name], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch (err) {
+    throw new Error(
+      `could not resolve ${name} through lisa-secrets-access.\n` +
+        `${String(err.stderr ?? err.message).trim()}\n` +
+        `It is the dispatcher's own credential; store it in the provider ` +
+        `rather than in .lisa.config.json.`
+    );
+  }
+}
+
+async function main() {
   const { skill, raw } = splitSkillFlag(process.argv.slice(2));
   const { params, rest } = parseInvocation(raw);
   const surface = resolveExecutionEnv(params);
@@ -247,6 +433,15 @@ function main() {
   // the repository-local skill, so an interactive run, a scheduled run, and a
   // recovery run all execute one contract.
   const prompt = `$${skill} ${rest}`.trim();
+
+  if (surface === "claude-web") {
+    const { sessionId, url } = await dispatchClaudeWeb(block, prompt, rest);
+    console.log(`dispatched: ${sessionId}`);
+    if (url) console.log(url);
+    console.log(`recorded in ${LEDGER}; not polling — this process is done.`);
+    return;
+  }
+
   const taskId = dispatchCodexCloud(block, prompt, rest);
 
   console.log(`dispatched: ${taskId}`);
@@ -255,10 +450,11 @@ function main() {
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {
-  try {
-    main();
-  } catch (err) {
+  // Awaited rather than called bare: one dispatch path is async, so a synchronous
+  // try/catch would let a rejection escape as an unhandled rejection and exit 0 —
+  // reporting dispatched work that was never accepted.
+  main().catch(err => {
     console.error(err.message);
     process.exit(1);
-  }
+  });
 }

package/plugins/src/base/skills/lisa-setup-remote-env/SKILL.md

@@ -13,11 +13,31 @@ Prepare a remote surface so a host project can execute there. Today that means *
 The remote environment's own configuration fields stay **one line into the repository**. Nothing else is pasted into a vendor UI.
 
 ```text
-setup:       bash "$HOME"/*/scripts/lisa-remote-env/setup.sh
-maintenance: bash "$HOME"/*/scripts/lisa-remote-env/setup.sh
+setup:       for f in scripts/lisa-remote-env/setup.sh */scripts/lisa-remote-env/setup.sh; do [ -f "$f" ] && exec bash "$f"; done; echo "lisa-remote-env entrypoint not found under $PWD" >&2; exit 1
+maintenance: for f in scripts/lisa-remote-env/setup.sh */scripts/lisa-remote-env/setup.sh; do [ -f "$f" ] && exec bash "$f"; done; echo "lisa-remote-env entrypoint not found under $PWD" >&2; exit 1
 ```
 
-**That line is identical for every project.** Nothing in it names the repository or the package manager, so it can be pasted unchanged into any project's environment. The glob is what locates the checkout — Claude Code web runs this field from `$HOME` while the clone lands one level down — and the script then anchors itself on the repository root.
+**That line is identical for every project AND every surface.** Nothing in it names the
+repository, the package manager, or a home directory, so it can be pasted unchanged anywhere.
+
+Locating the checkout is the only hard part, because the surfaces disagree about where the
+field runs:
+
+| Surface | cwd when the field runs | Checkout |
+| --- | --- | --- |
+| Codex Cloud | **is** the checkout | `/workspace/<repo>` |
+| Claude Code web | `$HOME` | `$HOME/<repo>` |
+
+So both candidates are tried **relative to cwd** — the checkout itself, then one level down —
+and neither mentions `$HOME`. An earlier version of this field used
+`bash "$HOME"/*/scripts/...`, which works on Claude Code web and fails on Codex Cloud, where
+the checkout is not under `$HOME` at all: the glob matches nothing and bash reports
+`No such file or directory` for a path still containing a literal `*`.
+
+`exec` on the first hit means no subshell and no `ls` output to parse, and the explicit
+`exit 1` means a missing entrypoint says so rather than the field silently succeeding. The
+script then anchors itself on the repository root, so it behaves the same however it was
+reached.
 
 They are the same command. A container may be built fresh or resumed from cache; every step is idempotent and version-aware, so running it twice is correct, and running it on resume is what picks up a rotated value, an edited note, or a changed version pin.
 
@@ -136,8 +156,8 @@ When emitting, produce exactly:
 ```text
 Environment name:  <project> remote executor
 Repository:        <org>/<repo>        (must be the default checkout)
-Setup script:      bash "$HOME"/*/scripts/lisa-remote-env/setup.sh
-Maintenance:       bash "$HOME"/*/scripts/lisa-remote-env/setup.sh
+Setup script:      for f in scripts/lisa-remote-env/setup.sh */scripts/lisa-remote-env/setup.sh; do [ -f "$f" ] && exec bash "$f"; done; echo "lisa-remote-env entrypoint not found under $PWD" >&2; exit 1
+Maintenance:       for f in scripts/lisa-remote-env/setup.sh */scripts/lisa-remote-env/setup.sh; do [ -f "$f" ] && exec bash "$f"; done; echo "lisa-remote-env entrypoint not found under $PWD" >&2; exit 1
                    (identical for every project — the script finds the
                    checkout and installs from the committed lockfile)
 Environment vars:  LISA_SECRETS_SURFACE=codex-cloud

package/plugins/src/base/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs

@@ -299,18 +299,29 @@ export function installAssets(cwd = process.cwd()) {
 }
 
 /**
- * The setup field, identical for every project.
+ * The setup field, identical for every project and every surface.
  *
- * Names neither the repository nor its package manager. Claude Code web runs
- * this field from `$HOME` while the checkout sits one level down, so the glob
- * locates the script; the script then anchors itself on the repository root and
- * installs dependencies from whichever lockfile the project commits.
+ * Names neither the repository nor its package manager, and deliberately not
+ * `$HOME` either: the surfaces disagree about where the field runs. Codex Cloud
+ * runs it inside the checkout, Claude Code web runs it from `$HOME` with the
+ * checkout one level down, and on Codex Cloud the checkout is not under `$HOME`
+ * at all — so a `$HOME` glob matched nothing there and bash was handed a path
+ * still containing a literal asterisk.
  *
- * A field that named both was a string a human had to get right, in a settings
- * box with no review, no version history and no test — and the logic it encoded
- * belongs in a file that has all three.
+ * Both candidates are therefore tried relative to cwd. `exec` on the first hit
+ * avoids a subshell and avoids parsing `ls`; the explicit `exit 1` means a
+ * missing entrypoint says so rather than the field quietly succeeding. The
+ * script then anchors itself on the repository root and installs dependencies
+ * from whichever lockfile the project commits.
+ *
+ * A field that named the repository and package manager was a string a human
+ * had to get right, in a settings box with no review, no version history and no
+ * test — and the logic it encoded belongs in a file that has all three.
  */
-const SETUP_FIELD = `bash "$HOME"/*/scripts/lisa-remote-env/setup.sh`;
+export const SETUP_FIELD =
+  "for f in scripts/lisa-remote-env/setup.sh */scripts/lisa-remote-env/setup.sh; " +
+  'do [ -f "$f" ] && exec bash "$f"; done; ' +
+  'echo "lisa-remote-env entrypoint not found under $PWD" >&2; exit 1';
 
 /**
  * The settings block that wires the session-start hook into a repository.

package/scripts/lisa-remote-env/setup.sh

@@ -13,9 +13,21 @@
 # and emphatically not in a vendor settings field.
 set -euo pipefail
 
+# Claude Code web runs the environment setup field from $HOME, while the
+# checkout lives at $HOME/<repo>. If this installed copy is invoked by absolute
+# path, move back to the repository root before resolving project-local files.
+script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+case "$script_dir" in
+  */scripts/lisa-remote-env)
+    cd "$script_dir/../.."
+    ;;
+esac
+
 # Node is the one thing that cannot be installed by the installer, since the
-# installer is written in it. Fail with an actionable message rather than a
-# "command not found" forty lines deep.
+# installer is written in it. Checked before the dependency install rather than
+# after: every package manager below is itself a node program, so a missing node
+# would otherwise surface as that manager failing under `set -e`, and the script
+# would exit on a confusing error instead of this actionable one.
 if ! command -v node >/dev/null 2>&1; then
   echo "node is required to prepare this environment but is not present." >&2
   echo "It cannot be installed by the toolchain step, because that step runs" >&2
@@ -23,6 +35,62 @@ if ! command -v node >/dev/null 2>&1; then
   exit 1
 fi
 
+# Install the project's dependencies, unless the caller already did.
+#
+# This lives here rather than in the vendor's settings field so that field can
+# be one identical line for every project. Naming the package manager there
+# meant a Claude environment for an npm project and one for a bun project
+# differed by a string a human had to get right, in a box with no review, no
+# version history, and no test.
+#
+# Which manager is decided by the lockfile that is actually committed, never
+# guessed: a guessed one fails on the container's first command with an error
+# blaming the project rather than the guess.
+#
+# Skipped when node_modules already exists, which is what makes this cheap on a
+# resumed container and correct to run twice.
+if [ "${LISA_SKIP_INSTALL:-}" != "1" ] && [ ! -d node_modules ]; then
+  if [ -f bun.lock ] || [ -f bun.lockb ]; then install_cmd="bun install"
+  elif [ -f pnpm-lock.yaml ]; then install_cmd="pnpm install --frozen-lockfile"
+  elif [ -f yarn.lock ]; then
+    # Yarn Classic and Berry spell the same intent differently, and each
+    # rejects the other's flag. The lockfile itself says which is in use:
+    # Yarn 1 writes a "# yarn lockfile v1" header, Berry does not.
+    if head -5 yarn.lock | grep -q "yarn lockfile v1"; then
+      install_cmd="yarn install --frozen-lockfile"
+    else
+      install_cmd="yarn install --immutable"
+    fi
+  elif [ -f package-lock.json ]; then install_cmd="npm ci"
+  else install_cmd=""
+  fi
+
+  if [ -n "$install_cmd" ]; then
+    echo "Installing dependencies with: $install_cmd"
+    # CI=1 so lifecycle scripts take their automation path and leave the
+    # checkout alone. A remote-env setup is automation by definition, and a
+    # postinstall that rewrites tracked files here breaks any skill with a
+    # clean-checkout precondition — which the publishing skills have, because
+    # their diff is contractually bounded and merged without human review.
+    #
+    # Lisa's own postinstall already guards on exactly this variable, so this
+    # is an existing convention rather than a new one.
+    #
+    # NOT --ignore-scripts: that would also stop patch-package, so a project
+    # relying on patched dependencies would silently get unpatched ones — a
+    # quieter failure than the one being fixed.
+    #
+    # Without it the bug is cache-dependent, not deterministic: a fresh
+    # container installs and dirties the tree, a resumed one skips the install
+    # and succeeds. That reads as flakiness rather than a cause.
+    CI=1 $install_cmd
+  else
+    # Not fatal on its own. A project may carry no lockfile and still have the
+    # skill in a checkout directory, so let the resolver below decide.
+    echo "No lockfile found; skipping dependency install." >&2
+  fi
+fi
+
 # Where the skill lives depends on how this project's harness receives it, and
 # the two delivery models differ in a way that matters here.
 #
@@ -57,9 +125,10 @@ if [ -z "$runner" ]; then
   echo "yet: Claude and Codex receive Lisa skills as an installed plugin, which" >&2
   echo "is not part of a clone, so node_modules is the only copy present." >&2
   echo >&2
-  echo "Install dependencies before this script runs. The environment's setup" >&2
-  echo "command should be the install and this script together, for example:" >&2
-  echo "  bun install && bash scripts/lisa-remote-env/setup.sh" >&2
+  echo "This script installs dependencies itself, so reaching here means the" >&2
+  echo "install did not produce the package, or the project has no lockfile" >&2
+  echo "identifying its package manager. Check that @codyswann/lisa is a" >&2
+  echo "dependency and that a lockfile is committed." >&2
   echo >&2
   echo "If dependencies are installed, run 'lisa apply' so the skills are" >&2
   echo "present, then re-run setup." >&2