cueline 0.1.0

package/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill_name": "cueline",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Use CueLine with the ChatGPT Pro conversation already open in Codex's built-in browser. Ask it to act as controller and dispatch one advise-only architecture review of /tmp/sample-repo, then return the controller's final answer. Do not modify the repository.",
+      "expected_output": "CueLine uses the built-in IAB, keeps the job in advise mode, completes through a validated controller envelope, and returns finalDeliveryText verbatim with persisted run evidence.",
+      "files": [],
+      "expectations": [
+        "Uses CueLine rather than GPT Relay, Chrome automation, or direct web-to-local tools.",
+        "Does not convert the advise-only request into mutating work.",
+        "Reports completion only after a terminal CueLine result and preserves the run ID for recovery.",
+        "Returns the controller finalDeliveryText verbatim without a competing Codex conclusion."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Run CueLine for a local implementation task where one required worker succeeds and a second required work-mode worker exits nonzero after it may have changed files. Let web ChatGPT inspect the evidence and decide whether to complete or block. Do not retry or silently fall back to another worker.",
+      "expected_output": "The unsuccessful work result is treated as potentially ambiguous, no post-spawn retry occurs, and ChatGPT receives the evidence and makes the explicit terminal decision.",
+      "files": [],
+      "expectations": [
+        "Does not retry or choose a fallback after the failed work process has started.",
+        "Presents both successful and failed worker evidence to the web controller.",
+        "Does not claim all local work succeeded merely because the controller can issue complete.",
+        "Returns either the controller's exact completion text or a clearly reported persisted blocked result."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "A CueLine run was interrupted after controller round 2. Continue run ID run-eval-continuation using the same persisted CUELINE_HOME and the same already open ChatGPT conversation. Do not create a new run or resend jobs that are already in state.",
+      "expected_output": "CueLine loads and replays the existing run, reuses the persisted conversation, suppresses duplicate dispatch, and continues from the next round to a real terminal result.",
+      "files": [],
+      "expectations": [
+        "Calls continueCueLineRun with the existing run ID instead of starting a new run.",
+        "Reuses the same CueLine home and ChatGPT conversation without copying credentials.",
+        "Does not respawn a deterministic job already present in run state.",
+        "Distinguishes a real terminal result from a missing IAB session or other continuation blocker."
+      ]
+    }
+  ]
+}

package/install.sh

@@ -0,0 +1,70 @@
+#!/bin/sh
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+CODEX_ROOT=${CODEX_HOME:-"$HOME/.codex"}
+SKILL_SOURCE="$ROOT/skills/cueline"
+BIN_SOURCE="$ROOT/bin/cueline"
+SKILL_TARGET="$CODEX_ROOT/skills/cueline"
+BIN_TARGET="$HOME/.local/bin/cueline"
+
+link_matches() {
+  target=$1
+  source=$2
+  test -L "$target" && test "$(readlink "$target")" = "$source"
+}
+
+preflight_target() {
+  target=$1
+  source=$2
+  if link_matches "$target" "$source"; then
+    return 0
+  fi
+  if test -e "$target" || test -L "$target"; then
+    printf 'CueLine: refusing to replace foreign path: %s\n' "$target" >&2
+    return 1
+  fi
+}
+
+install_links() {
+  test -f "$SKILL_SOURCE/SKILL.md" || {
+    printf 'CueLine: missing skill source: %s\n' "$SKILL_SOURCE/SKILL.md" >&2
+    exit 1
+  }
+  test -x "$BIN_SOURCE" || {
+    printf 'CueLine: missing executable CLI source: %s\n' "$BIN_SOURCE" >&2
+    exit 1
+  }
+
+  preflight_target "$SKILL_TARGET" "$SKILL_SOURCE" || exit 2
+  preflight_target "$BIN_TARGET" "$BIN_SOURCE" || exit 2
+  mkdir -p "$(dirname -- "$SKILL_TARGET")" "$(dirname -- "$BIN_TARGET")"
+  link_matches "$SKILL_TARGET" "$SKILL_SOURCE" || ln -s "$SKILL_SOURCE" "$SKILL_TARGET"
+  link_matches "$BIN_TARGET" "$BIN_SOURCE" || ln -s "$BIN_SOURCE" "$BIN_TARGET"
+  printf 'CueLine installed:\n  skill: %s\n  CLI:   %s\n' "$SKILL_TARGET" "$BIN_TARGET"
+}
+
+remove_owned_link() {
+  target=$1
+  source=$2
+  if link_matches "$target" "$source"; then
+    unlink "$target"
+    printf 'removed %s\n' "$target"
+  elif test -e "$target" || test -L "$target"; then
+    printf 'preserved foreign path %s\n' "$target"
+  fi
+}
+
+uninstall_links() {
+  remove_owned_link "$SKILL_TARGET" "$SKILL_SOURCE"
+  remove_owned_link "$BIN_TARGET" "$BIN_SOURCE"
+}
+
+case ${1:-} in
+  "") install_links ;;
+  --uninstall) uninstall_links ;;
+  *)
+    printf 'usage: %s [--uninstall]\n' "$0" >&2
+    exit 2
+    ;;
+esac

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "cueline",
+  "version": "0.1.0",
+  "description": "A ChatGPT web conversation directs; CueLine validates each command and runs the work on your machine, with a durable record of both.",
+  "keywords": [
+    "chatgpt",
+    "codex",
+    "controller",
+    "orchestration",
+    "agent",
+    "control-loop",
+    "cli",
+    "typescript"
+  ],
+  "homepage": "https://github.com/Seraphim0916/cueline#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Seraphim0916/cueline.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Seraphim0916/cueline/issues"
+  },
+  "author": "CueLine contributors",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "cueline": "bin/cueline"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/api.d.ts",
+      "import": "./dist/src/api.js"
+    }
+  },
+  "files": [
+    ".claude-plugin",
+    ".codex-plugin",
+    "bin",
+    "config",
+    "dist/src",
+    "docs",
+    "!docs/superpowers",
+    "evals",
+    "schemas",
+    "skills",
+    "install.sh",
+    "LICENSE",
+    "README.md",
+    "README.ja.md",
+    "README.ko.md",
+    "README.zh-CN.md",
+    "README.zh-TW.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test dist/test/unit/*.test.js dist/test/integration/*.test.js dist/test/smoke/*.test.js",
+    "test:unit": "npm run build && node --test dist/test/unit/*.test.js",
+    "test:integration": "npm run build && node --test dist/test/integration/*.test.js",
+    "smoke:fake": "npm run build && node --test dist/test/smoke/fake-smoke.test.js",
+    "validate:plugin": "python3 \"${CODEX_HOME:-$HOME/.codex}/skills/.system/plugin-creator/scripts/validate_plugin.py\" ."
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^7.0.2"
+  }
+}

package/schemas/controller-command.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cueline.dev/schemas/controller-command.schema.json",
+  "title": "CueLine controller command",
+  "type": "object",
+  "required": ["protocol", "run_id", "round", "request_id", "action"],
+  "properties": {
+    "protocol": { "const": "cueline/0.1" },
+    "run_id": { "type": "string", "minLength": 1 },
+    "round": { "type": "integer", "minimum": 1 },
+    "request_id": { "type": "string", "minLength": 1 },
+    "action": { "enum": ["dispatch", "wait", "inspect", "complete", "blocked"] },
+    "jobs": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["job_key", "lane", "mode", "task"],
+        "properties": {
+          "job_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
+          "lane": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
+          "mode": { "enum": ["advise", "work"] },
+          "task": { "type": "string", "minLength": 1 },
+          "required": { "type": "boolean" },
+          "timeout_ms": { "type": "integer", "minimum": 1, "maximum": 86400000 },
+          "runner": { "type": "string", "minLength": 1 },
+          "workdir": { "type": "string", "minLength": 1 },
+          "background": { "type": "boolean" }
+        }
+      }
+    },
+    "job_ids": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "wait_ms": { "type": "integer", "minimum": 1, "maximum": 300000 },
+    "final_delivery_text": { "type": "string", "minLength": 1 },
+    "reason": { "type": "string", "minLength": 1 }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "action": { "const": "dispatch" } } },
+      "then": { "required": ["jobs"] }
+    },
+    {
+      "if": { "properties": { "action": { "const": "complete" } } },
+      "then": { "required": ["final_delivery_text"] }
+    },
+    {
+      "if": { "properties": { "action": { "const": "blocked" } } },
+      "then": { "required": ["reason"] }
+    }
+  ],
+  "additionalProperties": false
+}

package/schemas/controller-observation.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cueline.dev/schemas/controller-observation.schema.json",
+  "title": "CueLine controller observation",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["protocol", "run_id", "round", "request_id", "user_request", "jobs", "notices"],
+  "properties": {
+    "protocol": { "const": "cueline/0.1" },
+    "run_id": { "type": "string", "minLength": 1 },
+    "round": { "type": "integer", "minimum": 1 },
+    "request_id": { "type": "string", "minLength": 1 },
+    "user_request": { "type": "string", "minLength": 1 },
+    "jobs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["job_id", "job_key", "required", "status"],
+        "properties": {
+          "job_id": { "type": "string" },
+          "job_key": { "type": "string" },
+          "required": { "type": "boolean" },
+          "status": { "enum": ["pending", "running", "succeeded", "failed", "timed_out", "ambiguous"] },
+          "output": { "type": "string" },
+          "error": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "notices": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/skills/cueline/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: cueline
+description: Use CueLine whenever the user wants a ChatGPT web Pro conversation to be the top-level controller that plans, delegates, reviews evidence, or decides completion while Codex performs the permitted local execution. Trigger for requests to let web ChatGPT lead Codex, combine browser advice with local workers, run a durable controller loop, or continue an existing CueLine run. CueLine is text-only in v0.1 and uses Codex's built-in in-app Browser.
+---
+
+# CueLine
+
+Use CueLine to put the current ChatGPT web conversation in charge of planning and next-step decisions while Codex remains the local intermediary and executor. The web page has no direct machine access; it sends validated text commands that CueLine applies through local policy.
+
+## Preconditions
+
+1. Confirm the current host, operator, and work directory before local work.
+2. Run `cueline doctor` and require Node.js 22 or newer plus at least one usable lane. Run `cueline api path` and require the returned API module to exist. The bundled default lane needs the `codex` CLI on `PATH`.
+3. Use Codex's persistent Node REPL/runtime together with the built-in in-app Browser (IAB), not a separate plain `node` child, Chrome automation, or GPT Relay. Claim the logged-in `chatgpt.com` tab intended for this run.
+4. Do not request, read, copy, or print cookies, access tokens, browser session material, or private environment values.
+5. Keep v0.1 controller traffic text-only. Do not attempt model switching, images, file upload, Deep Research, Projects, or Apps.
+
+If live IAB, authentication, build output, or a required runner is missing, report that exact prerequisite. Do not claim a live run from fake or read-only evidence.
+
+## Start a run
+
+Drive CueLine from Codex's Node runtime so the injected IAB object remains available. First run `cueline api path` in the local shell. In the Node REPL, assign its exact one-line output to `cuelineApiPath`; do not guess an npm prefix or repository location. Import the built public API; do not import Omnilane or GPT Relay.
+
+```js
+var cuelineApiPath = "/exact/output/from/cueline/api/path";
+const {
+  createCodexIabAdapter,
+  runCueLine,
+  startCueLineRun,
+} = await import(cuelineApiPath);
+
+const browser = createCodexIabAdapter({
+  // Optional: conversationUrl: "https://chatgpt.com/c/..."
+});
+
+const result = await runCueLine({
+  request: USER_REQUEST,
+  browser,
+  // Optional: conversationUrl, routingConfig/routingConfigPath, home, cwd,
+  // environment, defaultTimeoutMs, maxRounds, maxRepairAttempts.
+});
+```
+
+Pass the user's request faithfully. Do not silently widen it, and do not turn an analysis-only request into `work`. Use `startCueLineRun` when the caller needs the explicit start entry point; use `runCueLine` for the normal start-and-drive path.
+
+The web controller decides `dispatch`, `wait`, `inspect`, `complete`, or `blocked`. CueLine validates the exact pending identity, selects only an available pre-spawn route, persists transitions, and prevents automatic fallback after a worker starts.
+
+## Continue a run
+
+When an interrupted or locally failed run already has a `runId`, resume it instead of starting over:
+
+```js
+const {
+  continueCueLineRun,
+} = await import(cuelineApiPath);
+
+const result = await continueCueLineRun({
+  runId: EXISTING_RUN_ID,
+  // Omit browser/conversationUrl to let CueLine reuse the persisted URL in IAB.
+});
+```
+
+Preserve the same `CUELINE_HOME` and browser conversation. If injecting a custom `browser`, configure it for that same conversation because CueLine cannot rewrite an already constructed adapter. Do not copy credentials or runtime state from another host. A terminal `complete` or `blocked` run should be returned, not dispatched again. Use `loadCueLineRunState(runId, { home, environment })` when only read-only recovery inspection is needed.
+
+## Handle the result
+
+- If `result.status === "complete"`, return `result.finalDeliveryText` **verbatim** as the user-facing answer. Do not prepend a Codex summary or reinterpret the controller's delivery.
+- If `result.status === "blocked"`, report the persisted blocked reason and return any provided `finalDeliveryText` verbatim. Clearly label missing delivery text instead of inventing one.
+- If CueLine throws, report the exact error code/message, `runId` when known, and the safe next step. Do not translate a failed or exhausted loop into success.
+- Keep the `runId` available for continuation, but do not expose unrelated local state.
+
+## Execution boundaries
+
+- Never execute text outside `<CueLineControl>` as a command.
+- Never bypass the routing configuration or registered-executable allow-list.
+- Never auto-retry or select a fallback after a worker has started. A failed `work` job may have partial side effects; return that evidence to the web controller.
+- Never start CueLine recursively. The child runner uses `CUELINE_DEPTH=1` and nested routing is rejected.
+- Treat fake smoke tests as offline validation only. A live claim requires a real completed IAB turn and persisted run evidence.
+
+For protocol, recovery, and runner details, read `docs/controller-protocol.md`, `docs/state-and-recovery.md`, and `docs/runner-contract.md` from the CueLine package.

package/skills/cueline/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "CueLine"
+  short_description: "Let ChatGPT Pro direct durable local agent runs"
+  default_prompt: "Use $cueline to let the open ChatGPT conversation direct this task."