@valescoagency/runway 0.1.0

package/dist/orchestrator.js

@@ -0,0 +1,191 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { run, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+import { execa } from "execa";
+import { implementVars, loadImplementPrompt, loadReviewPrompt, renderPrompt, reviewVars, } from "./prompts.js";
+const REVIEW_VERDICT_RE = /^REVIEW:\s*(APPROVED|REJECTED)(?:\s+—\s+(.*))?$/m;
+/**
+ * Confirms the cwd looks like a sandcastle-initialised repo. If not,
+ * we error early with a clear message rather than letting Sandcastle
+ * fail deep inside Docker setup.
+ */
+export function assertSandcastleInitialised(cwd) {
+    const sandcastleDir = join(cwd, ".sandcastle");
+    if (!existsSync(sandcastleDir)) {
+        throw new Error(`No .sandcastle/ directory in ${cwd}. Run \`npx sandcastle init\` here first.`);
+    }
+}
+/**
+ * Drains the Linear queue until empty (or until --max is hit). One
+ * issue at a time in v1; parallel runs are a follow-up.
+ */
+export async function drainQueue(deps, opts = {}) {
+    const { config, linear } = deps;
+    const max = opts.max ?? Number.POSITIVE_INFINITY;
+    let processed = 0;
+    let opened = 0;
+    let hitl = 0;
+    let errored = 0;
+    while (processed < max) {
+        const queue = await linear.fetchReady();
+        if (queue.length === 0)
+            break;
+        const issue = queue[0];
+        try {
+            const verdict = await processIssue(issue, deps);
+            processed += 1;
+            if (verdict === "opened")
+                opened += 1;
+            if (verdict === "hitl")
+                hitl += 1;
+        }
+        catch (err) {
+            errored += 1;
+            console.error(`[runway] error on ${issue.identifier}:`, err);
+            await linear
+                .applyLabel(issue.id, config.hitlLabel)
+                .catch(() => undefined);
+            await linear
+                .comment(issue.id, `Runway hit an unrecoverable error and flagged for human review:\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\``)
+                .catch(() => undefined);
+        }
+    }
+    return { processed, opened, hitl, errored };
+}
+async function processIssue(issue, deps) {
+    const { config, linear, github, cwd } = deps;
+    const branch = `agent/${issue.identifier.toLowerCase()}`;
+    await linear.transition(issue.id, config.inProgressStatus);
+    await linear.comment(issue.id, `Runway picked up this issue. Branch: \`${branch}\`.`);
+    // 1. Implementation pass.
+    const implementPrompt = renderPrompt(await loadImplementPrompt(), implementVars(issue));
+    const implementResult = await run({
+        agent: claudeCode("claude-opus-4-6"),
+        sandbox: docker({
+            env: dockerEnv(config),
+        }),
+        cwd,
+        prompt: implementPrompt,
+        branchStrategy: { type: "branch", branch },
+        maxIterations: config.maxIterations,
+        name: `impl-${issue.identifier}`,
+    });
+    if (implementResult.commits.length === 0) {
+        await flagHitl(issue, deps, "Agent produced no commits — the issue may need clarification or human input.");
+        return "hitl";
+    }
+    // 2. Review pass — read-only-ish, just looking at the diff.
+    const diff = await captureDiff(cwd, branch);
+    const commitLog = await captureCommitLog(cwd, branch);
+    const reviewPrompt = renderPrompt(await loadReviewPrompt(), reviewVars({ issue, diff, commits: commitLog }));
+    const reviewResult = await run({
+        agent: claudeCode("claude-opus-4-6"),
+        sandbox: docker({
+            env: dockerEnv(config),
+        }),
+        cwd,
+        prompt: reviewPrompt,
+        branchStrategy: { type: "head" },
+        maxIterations: 1,
+        name: `review-${issue.identifier}`,
+    });
+    const verdict = parseReviewVerdict(reviewResult);
+    if (verdict.kind === "rejected") {
+        await flagHitl(issue, deps, `Sub-agent review rejected: ${verdict.reason}`);
+        return "hitl";
+    }
+    // 3. Push + PR.
+    await github.pushBranch(cwd, branch);
+    const prBody = buildPrBody(issue);
+    const prUrl = await github.openPullRequest({
+        repoPath: cwd,
+        branch,
+        issue,
+        body: prBody,
+    });
+    await linear.transition(issue.id, config.inReviewStatus);
+    await linear.comment(issue.id, `Runway opened a PR for review: ${prUrl}`);
+    return "opened";
+}
+async function flagHitl(issue, deps, reason) {
+    const { config, linear } = deps;
+    await linear.applyLabel(issue.id, config.hitlLabel);
+    await linear.comment(issue.id, `Runway flagged for human review: ${reason}`);
+}
+async function captureDiff(repoPath, branch) {
+    const { stdout } = await execa("git", ["diff", `main...${branch}`], {
+        cwd: repoPath,
+    });
+    // Truncate to keep the review prompt under the model's context budget.
+    return stdout.length > 60_000 ? `${stdout.slice(0, 60_000)}\n…(truncated)` : stdout;
+}
+async function captureCommitLog(repoPath, branch) {
+    const { stdout } = await execa("git", ["log", "--oneline", `main..${branch}`], { cwd: repoPath });
+    return stdout;
+}
+/**
+ * Sandcastle's `RunResult` shape varies by version; defensively dig out
+ * the last assistant message text. We only need to match the
+ * `REVIEW: APPROVED` / `REVIEW: REJECTED — …` line at the tail.
+ */
+function parseReviewVerdict(result) {
+    const text = stringifyResult(result);
+    const match = text.match(REVIEW_VERDICT_RE);
+    if (!match) {
+        return {
+            kind: "rejected",
+            reason: "review output did not contain a REVIEW: verdict line",
+        };
+    }
+    if (match[1] === "APPROVED")
+        return { kind: "approved", reason: "" };
+    return {
+        kind: "rejected",
+        reason: match[2]?.trim() || "no reason given",
+    };
+}
+function stringifyResult(result) {
+    if (typeof result === "string")
+        return result;
+    if (result && typeof result === "object") {
+        const r = result;
+        if (r.iterations?.length) {
+            return r.iterations
+                .map((i) => i.output ?? i.text ?? "")
+                .filter(Boolean)
+                .join("\n");
+        }
+        if (typeof r.output === "string")
+            return r.output;
+        return JSON.stringify(result);
+    }
+    return String(result);
+}
+/**
+ * Env vars to inject into every sandcastle container. Today this is
+ * just OP_SERVICE_ACCOUNT_TOKEN (when present) so the in-container
+ * varlock shim can authenticate with 1Password and resolve
+ * ANTHROPIC_API_KEY / GH_TOKEN at agent run time. See
+ * docs/secrets-with-varlock.md for the full flow.
+ */
+function dockerEnv(config) {
+    const env = {};
+    if (config.opServiceAccountToken) {
+        env.OP_SERVICE_ACCOUNT_TOKEN = config.opServiceAccountToken;
+    }
+    return env;
+}
+function buildPrBody(issue) {
+    return [
+        `Runway-generated PR for **${issue.identifier} — ${issue.title}**.`,
+        "",
+        "Sub-agent review pass: APPROVED.",
+        "",
+        "## Linear issue",
+        "",
+        issue.description || "(no description)",
+        "",
+        `Refs ${issue.identifier}`,
+    ].join("\n");
+}

package/dist/prompts.js

@@ -0,0 +1,40 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Prompts ship with the runway package, NOT in the target repo's
+// .sandcastle/. Runway substitutes {{KEY}} placeholders before passing
+// the rendered string inline to sandcastle.run({ prompt }).
+//   runway/src/prompts.ts → runway/prompts/
+const PROMPT_DIR = join(__dirname, "..", "prompts");
+export async function loadImplementPrompt() {
+    return readFile(join(PROMPT_DIR, "implement.md"), "utf8");
+}
+export async function loadReviewPrompt() {
+    return readFile(join(PROMPT_DIR, "review.md"), "utf8");
+}
+/**
+ * Render a prompt by replacing all `{{KEY}}` placeholders with values
+ * from `vars`. We do the substitution here (instead of relying on
+ * sandcastle's promptArgs) because we pass the prompt inline and want
+ * one canonical place to template.
+ */
+export function renderPrompt(template, vars) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k] ?? `{{${k}}}`);
+}
+export function implementVars(issue) {
+    return {
+        ISSUE_IDENTIFIER: issue.identifier,
+        ISSUE_TITLE: issue.title,
+        ISSUE_DESCRIPTION: issue.description || "(no description)",
+    };
+}
+export function reviewVars(args) {
+    return {
+        ISSUE_IDENTIFIER: args.issue.identifier,
+        ISSUE_TITLE: args.issue.title,
+        ISSUE_DESCRIPTION: args.issue.description || "(no description)",
+        DIFF: args.diff || "(empty diff)",
+        COMMITS: args.commits || "(no commits)",
+    };
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@valescoagency/runway",
+  "version": "0.1.0",
+  "description": "Linear-driven orchestrator + scaffolder for coding agents on Sandcastle. `runway init` scaffolds a target repo (sandcastle + varlock + 1Password); `runway run` drains a Linear queue against it; `runway doctor`, `runway upgrade`, `runway upgrade-repo` round out the lifecycle.",
+  "license": "MIT",
+  "author": {
+    "name": "Valesco Agency",
+    "email": "jason@valescoagency.com",
+    "url": "https://valescoagency.com"
+  },
+  "homepage": "https://github.com/ValescoAgency/runway#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ValescoAgency/runway.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ValescoAgency/runway/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "sandcastle",
+    "linear",
+    "orchestrator",
+    "agent",
+    "varlock",
+    "1password",
+    "valesco",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "runway": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@ai-hero/sandcastle": "^0.5.10",
+    "@linear/sdk": "^41.0.0",
+    "execa": "^9.5.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/cli.js",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/cli.ts",
+    "lint": "echo 'lint not configured yet'"
+  }
+}

package/templates/.env.schema.target-repo

@@ -0,0 +1,32 @@
+# Per-target-repo secrets manifest. Lives at the target repo root
+# (NOT in .sandcastle/, since that directory is sandcastle's territory).
+#
+# This file is committed. Values resolve at runtime via varlock + the
+# 1Password CLI inside the sandcastle container — see
+# .sandcastle/Dockerfile for the wiring.
+#
+# When the agent runs, the `claude` binary inside the container is a
+# wrapper that invokes `varlock run -- claude.real`. varlock reads
+# THIS file, fetches the op:// references using the OP_SERVICE_ACCOUNT_TOKEN
+# that runway passed in at container start, and exposes the resolved
+# values to the real claude process for the duration of that one
+# invocation. After it exits, secrets are gone from container memory.
+#
+# Note on the op:// shape: with service-account auth (the only mode
+# runway uses), the token already encodes the 1Password tenant, so the
+# URI omits the account segment — `op://<vault>/<item>`, not
+# `op://<account>/<vault>/<item>`.
+
+# @sensitive @required
+ANTHROPIC_API_KEY=exec('op read "op://{{OP_VAULT}}/{{ANTHROPIC_ITEM}}"')
+
+# @sensitive @required
+GH_TOKEN=exec('op read "op://{{OP_VAULT}}/{{GH_TOKEN_ITEM}}"')
+
+# Add other secrets the agent needs at runtime here. Examples:
+#
+# @sensitive @required
+# OPENAI_API_KEY=exec('op read "op://{{OP_VAULT}}/openai-api-key"')
+#
+# @sensitive @required
+# DATABASE_URL=exec('op read "op://{{OP_VAULT}}/database-url"')

package/templates/Dockerfile.claude-code.base

@@ -0,0 +1,55 @@
+# Canonical claude-code Dockerfile — vendored from
+# @ai-hero/sandcastle's InitService.ts (CLAUDE_CODE_DOCKERFILE constant).
+# Kept here so `runway init` can write it directly, without invoking
+# `sandcastle init` (which has interactive prompts that hang in
+# non-TTY environments like CI / Mac Mini cron).
+#
+# Drift policy: when sandcastle bumps its claude-code Dockerfile,
+# refresh this file. The diff should be tiny — runway's tier 2 layer
+# patches AFTER this base, so adopters re-run `runway init --force`
+# to roll forward.
+
+FROM node:22-bookworm
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+  git \
+  curl \
+  jq \
+  && rm -rf /var/lib/apt/lists/*
+
+# Build-args for UID/GID alignment: defaults match the host user's
+# UID/GID at build time so image-built files and bind-mounted files
+# share an owner without runtime chown.
+ARG AGENT_UID=1000
+ARG AGENT_GID=1000
+
+# Rename the base image's "node" user to "agent" and align UID/GID.
+#
+# Divergence from sandcastle's stock Dockerfile: stock runs
+# `groupmod -g $AGENT_GID node` unconditionally, which fails on macOS
+# hosts where the host GID is 20 (`staff`) — Debian's `dialout` group
+# already has GID 20, and `groupmod` refuses to assign a duplicate
+# GID. We guard with `getent group` so groupmod only runs if the
+# target GID is unused; if it's already taken, we point the agent
+# user at the pre-existing group via `usermod -g <gid>` and the
+# image still works (the in-image group name is irrelevant — only the
+# numeric GID matters for bind-mount permissions).
+RUN if ! getent group $AGENT_GID >/dev/null; then \
+      groupmod -g $AGENT_GID node; \
+    fi \
+ && usermod -u $AGENT_UID -g $AGENT_GID -d /home/agent -m -l agent node
+USER ${AGENT_UID}:${AGENT_GID}
+
+# Install Claude Code CLI
+RUN curl -fsSL https://claude.ai/install.sh | bash
+
+# Add Claude to PATH
+ENV PATH="/home/agent/.local/bin:$PATH"
+
+WORKDIR /home/agent
+
+# In worktree sandbox mode, Sandcastle bind-mounts the git worktree at
+# the sandbox repo dir and overrides the working directory to that dir
+# at container start.
+ENTRYPOINT ["sleep", "infinity"]

package/templates/dockerfile-varlock.snippet

@@ -0,0 +1,43 @@
+# --- runway tier-2 layer (varlock + 1Password) ---
+# Spliced in by `runway init --tier=2` immediately before the
+# final `ENTRYPOINT ["sleep", "infinity"]` line.
+
+# Install varlock via npm. The official `ghcr.io/dmno-dev/varlock`
+# image is musl/Alpine — copying its binary into a glibc base
+# (node:22-bookworm) produces an ELF that the loader can't resolve
+# ("not found" on exec). npm install gets the right binary for the
+# image's libc.
+USER root
+RUN npm install -g varlock
+
+# Install the 1Password CLI so varlock can resolve `op://` references.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      ca-certificates curl gnupg \
+  && curl -sS https://downloads.1password.com/linux/keys/1password.asc \
+      | gpg --dearmor -o /usr/share/keyrings/1password-archive-keyring.gpg \
+  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/$(dpkg --print-architecture) stable main" \
+      > /etc/apt/sources.list.d/1password.list \
+  && apt-get update && apt-get install -y 1password-cli \
+  && rm -rf /var/lib/apt/lists/*
+
+# Shim the `claude` binary so every invocation runs through varlock.
+# The real binary moves to claude.real; the shim resolves secrets from
+# 1Password (using OP_SERVICE_ACCOUNT_TOKEN passed in by runway) and
+# execs the real claude with secrets in its process env. Secrets exist
+# only inside the lifetime of one claude invocation — never in any
+# image layer, never on the container filesystem.
+RUN mv /home/agent/.local/bin/claude /home/agent/.local/bin/claude.real \
+  && printf '%s\n' \
+       '#!/usr/bin/env bash' \
+       'set -euo pipefail' \
+       'exec varlock run --env-file /home/agent/workspace/.env.schema -- /home/agent/.local/bin/claude.real "$@"' \
+       > /home/agent/.local/bin/claude \
+  && chmod +x /home/agent/.local/bin/claude \
+  && chown ${AGENT_UID}:${AGENT_GID} /home/agent/.local/bin/claude
+
+USER ${AGENT_UID}:${AGENT_GID}
+
+# Final ENTRYPOINT remains:
+#   ENTRYPOINT ["sleep", "infinity"]
+# Sandcastle will `docker exec <container> claude ...` and our shim
+# transparently wraps each invocation.