codiedev 0.9.80 → 0.10.0-beta.10

package/dist/commands/agentsSdk.generated.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsPackage = exports.jsTypes = exports.jsIndex = exports.python = void 0;
+exports.python = "\"\"\"Codiedev agents SDK — the run primitive, from Python.\n\nInside a deployed agent (everything is already configured):\n\n    import codiedev_agents as agents\n\n    task = agents.input()                      # this run's input (JSON)\n    llm = agents.openai()                      # OpenAI client on the Codiedev gateway, traced\n    child = agents.run(\"summarize\", {\"text\": ...})   # start another agent as a child run\n    agents.output({\"summary\": child[\"output\"]})      # this run's result\n    agents.request()                           # webhook runs: method, headers, raw body\n    agents.respond({\"text\": \"on it\"})          # what a webhook caller waiting (?wait=) gets back\n\n    agents.state.get(\"cursor\")                 # per-agent storage that outlives runs\n    agents.state.set(\"cursor\", 42)\n    agents.step(\"fetch\", lambda: fetch())      # done once per run, even across retries\n    agents.start(\"triage\", {...}, delay=3600)  # start a run later (up to 7 days)\n    agents.request_approval(\"Refund $120?\", context={...})  # a person decides; a run acts on it\n    agents.attempt()                           # 1, or 2+ when this run is a retry\n\nOutside a run (a script, a notebook, another service), set CODIEDEV_TOKEN\n(your CLI token) and CODIEDEV_AGENTS_URL, then call agents.run() the same way.\nStandard library only, so it drops into any project.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport os\nimport time\nimport urllib.error\nimport urllib.parse\nimport urllib.request\nfrom typing import Any\n\n__all__ = [\n    \"input\", \"output\", \"request\", \"respond\", \"run\", \"start\", \"get\", \"openai\", \"attempt\",\n    \"state\", \"step\", \"request_approval\", \"get_approval\", \"AgentRunError\", \"StateConflict\",\n]\n\n_INPUT_PATH = os.environ.get(\"CODIEDEV_INPUT_PATH\", \"/agent/.codiedev/input.json\")\n_OUTPUT_PATH = os.environ.get(\"CODIEDEV_OUTPUT_PATH\", \"/agent/.codiedev/output.json\")\n_REQUEST_PATH = os.environ.get(\"CODIEDEV_REQUEST_PATH\", \"/agent/.codiedev/request.json\")\n_RESPONSE_PATH = os.environ.get(\"CODIEDEV_RESPONSE_PATH\", \"/agent/.codiedev/response.json\")\n# Set by `codiedev agents run --local`: state lives in this file instead of Codiedev.\n_STATE_PATH = os.environ.get(\"CODIEDEV_STATE_PATH\")\n_DONE = {\"succeeded\", \"failed\", \"cancelled\"}\n\n\nclass StateConflict(RuntimeError):\n    \"\"\"state.set(..., if_version=n) found the key at another version.\"\"\"\n\n    def __init__(self, key: str, version: int):\n        super().__init__(f\"state {key!r} changed (now version {version})\")\n        self.key = key\n        self.version = version\n\n\nclass AgentRunError(RuntimeError):\n    def __init__(self, run: dict):\n        super().__init__(f\"{run.get('agent')} run {run.get('id')} {run.get('status')}: {run.get('error') or 'no error message'}\")\n        self.run = run\n\n\ndef input(default: Any = None) -> Any:  # noqa: A001 - mirrors output()\n    \"\"\"This run's input, parsed from JSON (None when started without one).\"\"\"\n    try:\n        with open(_INPUT_PATH) as f:\n            value = json.load(f)\n    except FileNotFoundError:\n        return default\n    return default if value is None else value\n\n\ndef output(value: Any) -> None:\n    \"\"\"Set this run's result. Must be JSON-serializable; the last call wins.\"\"\"\n    os.makedirs(os.path.dirname(_OUTPUT_PATH), exist_ok=True)\n    with open(_OUTPUT_PATH, \"w\") as f:\n        json.dump(value, f)\n\n\ndef respond(body: Any = None, status: int = 200, headers: \"dict | None\" = None) -> None:\n    \"\"\"What a webhook caller gets back when it waits for the run (?wait=N):\n    a string is sent as text, anything else as JSON. Without respond(), a\n    waiting caller gets the run's output.\"\"\"\n    os.makedirs(os.path.dirname(_RESPONSE_PATH), exist_ok=True)\n    with open(_RESPONSE_PATH, \"w\") as f:\n        json.dump({\"status\": status, \"headers\": headers or {}, \"body\": body}, f)\n\n\ndef attempt() -> int:\n    \"\"\"This run's attempt: 1, or 2+ when it's a retry of a failed attempt.\"\"\"\n    return int(os.environ.get(\"CODIEDEV_ATTEMPT\", \"1\"))\n\n\ndef request() -> \"dict | None\":\n    \"\"\"For a webhook run: {\"method\", \"query\", \"headers\", \"body\"} with the raw\n    body, to verify the sender's signature. None for other runs.\"\"\"\n    try:\n        with open(_REQUEST_PATH) as f:\n            return json.load(f)\n    except FileNotFoundError:\n        return None\n\n\ndef _base() -> str:\n    url = os.environ.get(\"CODIEDEV_AGENTS_URL\", \"\").rstrip(\"/\")\n    if not url:\n        raise RuntimeError(\"Set CODIEDEV_AGENTS_URL (it's set for you inside a run)\")\n    return url\n\n\ndef _token() -> str:\n    # Inside a run: the run's token. A connected agent (running outside Codiedev): its own key.\n    # Otherwise: your CLI token.\n    key = os.environ.get(\"CODIEDEV_API_KEY\", \"\")\n    token = os.environ.get(\"CODIEDEV_RUN_TOKEN\") or (key if key.startswith(\"cdvm_\") else None) or os.environ.get(\"CODIEDEV_TOKEN\")\n    if not token:\n        raise RuntimeError(\"Set CODIEDEV_API_KEY to your connected agent's key, or CODIEDEV_TOKEN to your CLI token (inside a run it's set for you)\")\n    return token\n\n\ndef _request(method: str, path: str, body: dict | None = None, ok: tuple[int, ...] = ()) -> dict:\n    req = urllib.request.Request(\n        f\"{_base()}{path}\",\n        method=method,\n        data=json.dumps(body).encode() if body is not None else None,\n        headers={\"Authorization\": f\"Bearer {_token()}\", \"Content-Type\": \"application/json\"},\n    )\n    try:\n        with urllib.request.urlopen(req, timeout=30) as res:\n            return json.loads(res.read() or b\"{}\")\n    except urllib.error.HTTPError as err:\n        detail = err.read().decode(errors=\"replace\")\n        if err.code in ok:\n            return {\"_status\": err.code, **json.loads(detail or \"{}\")}\n        try:\n            detail = json.loads(detail).get(\"error\", detail)\n        except ValueError:\n            pass\n        raise RuntimeError(f\"Codiedev agents API {err.code}: {detail}\") from None\n\n\ndef start(\n    agent: str,\n    input: Any = None,  # noqa: A002\n    idempotency_key: str | None = None,\n    delay: float | None = None,\n    retries: int | None = None,\n) -> str:\n    \"\"\"Start a run and return its id without waiting. With an idempotency key,\n    a second start within a day returns the first run's id. delay (seconds,\n    up to 7 days) starts it later; retries overrides the agent's retries.\"\"\"\n    body: dict = {\"agent\": agent, \"input\": input}\n    if idempotency_key:\n        body[\"idempotencyKey\"] = idempotency_key\n    if delay:\n        body[\"delaySec\"] = int(delay)\n    if retries is not None:\n        body[\"retries\"] = retries\n    return _request(\"POST\", \"/api/agents/v1/run\", body)[\"runId\"]\n\n\ndef get(run_id: str) -> dict:\n    \"\"\"A run's status, input, output (parsed), error, log tail and children.\"\"\"\n    run = _request(\"GET\", f\"/api/agents/v1/run?id={run_id}\")\n    if isinstance(run.get(\"output\"), str):\n        try:\n            run[\"output\"] = json.loads(run[\"output\"])\n        except ValueError:\n            pass\n    return run\n\n\ndef run(\n    agent: str,\n    input: Any = None,  # noqa: A002\n    timeout: float = 900,\n    poll: float = 2.0,\n    check: bool = True,\n    idempotency_key: str | None = None,\n) -> dict:\n    \"\"\"Run an agent and wait for it. Returns the run; its result is run[\"output\"].\n\n    Inside a run this starts a child run, so the chain shows as one tree.\n    Raises AgentRunError if it fails (pass check=False to get the run anyway).\n    \"\"\"\n    run_id = start(agent, input, idempotency_key)\n    deadline = time.monotonic() + timeout\n    while True:\n        result = get(run_id)\n        if result.get(\"status\") in _DONE:\n            if check and result[\"status\"] != \"succeeded\":\n                raise AgentRunError(result)\n            return result\n        if time.monotonic() > deadline:\n            raise TimeoutError(f\"{agent} run {run_id} still {result.get('status')} after {timeout}s\")\n        time.sleep(poll)\n\n\nclass _State:\n    \"\"\"Per-agent key-value storage that outlives runs (values: any JSON, up\n    to 64 KB; 1,000 keys). Every write bumps the key's version; pass\n    if_version to write only if nobody else did since you read it.\"\"\"\n\n    def get(self, key: str, default: Any = None) -> Any:\n        value, _ = self.get_versioned(key)\n        return default if value is None else value\n\n    def get_versioned(self, key: str) -> \"tuple[Any, int]\":\n        \"\"\"(value, version); (None, 0) when the key isn't set.\"\"\"\n        if _STATE_PATH:\n            row = _local_state().get(key)\n            return (row[\"value\"], row[\"version\"]) if row else (None, 0)\n        res = _request(\"GET\", f\"/api/agents/v1/state?{urllib.parse.urlencode({'key': key, 'agent': _agent()})}\", ok=(404,))\n        if res.get(\"_status\") == 404:\n            return None, 0\n        return json.loads(res[\"value\"]), int(res[\"version\"])\n\n    def set(self, key: str, value: Any, if_version: \"int | None\" = None, ttl: \"float | None\" = None) -> int:\n        \"\"\"Store value; returns the new version. Raises StateConflict when\n        if_version is given and the key is at another version (0 = unset).\"\"\"\n        return self._write(key, value, if_version, ttl)\n\n    def delete(self, key: str, if_version: \"int | None\" = None) -> None:\n        self._write(key, None, if_version, None)\n\n    def list(self, prefix: str = \"\", values: bool = False) -> \"list[dict]\":  # noqa: A003\n        \"\"\"Keys (and with values=True, values) starting with prefix.\"\"\"\n        if _STATE_PATH:\n            rows = sorted((k, r) for k, r in _local_state().items() if k.startswith(prefix))\n            return [{\"key\": k, \"version\": r[\"version\"], **({\"value\": r[\"value\"]} if values else {})} for k, r in rows]\n        keys: list = []\n        after = None\n        while True:\n            params = {\"prefix\": prefix, \"values\": \"1\" if values else \"0\", \"limit\": 200, \"agent\": _agent()}\n            if after:\n                params[\"after\"] = after\n            page = _request(\"GET\", f\"/api/agents/v1/state?{urllib.parse.urlencode(params)}\")\n            for row in page[\"keys\"]:\n                if \"value\" in row:\n                    row[\"value\"] = json.loads(row[\"value\"])\n            keys.extend(page[\"keys\"])\n            after = page.get(\"next\")\n            if not after:\n                return keys\n\n    def update(self, key: str, fn, default: Any = None, retries: int = 10) -> Any:\n        \"\"\"Read-modify-write that's safe with runs in parallel: fn(old) -> new,\n        retried if another run wrote first. Returns the new value.\"\"\"\n        for _ in range(retries):\n            value, version = self.get_versioned(key)\n            new = fn(default if value is None else value)\n            try:\n                self.set(key, new, if_version=version)\n                return new\n            except StateConflict:\n                time.sleep(0.05)\n        raise StateConflict(key, -1)\n\n    def _write(self, key: str, value: Any, if_version: \"int | None\", ttl: \"float | None\") -> int:\n        if _STATE_PATH:\n            data = _local_state()\n            current = data.get(key, {}).get(\"version\", 0)\n            if if_version is not None and if_version != current:\n                raise StateConflict(key, current)\n            if value is None:\n                data.pop(key, None)\n            else:\n                data[key] = {\"value\": value, \"version\": current + 1}\n            with open(_STATE_PATH, \"w\") as f:\n                json.dump(data, f, indent=2)\n            return 0 if value is None else current + 1\n        body: dict = {\"key\": key, \"value\": value, \"agent\": _agent()}\n        if if_version is not None:\n            body[\"ifVersion\"] = if_version\n        if ttl:\n            body[\"ttlSec\"] = int(ttl)\n        res = _request(\"POST\", \"/api/agents/v1/state\", body, ok=(409,))\n        if res.get(\"_status\") == 409:\n            raise StateConflict(key, int(res.get(\"version\", 0)))\n        return int(res.get(\"version\", 0))\n\n\ndef _agent() -> str:\n    # Inside a run the run token picks the agent; a CLI token needs it named.\n    return os.environ.get(\"CODIEDEV_AGENT\", \"\")\n\n\ndef _local_state() -> dict:\n    try:\n        with open(_STATE_PATH or \"\") as f:\n            return json.load(f)\n    except (FileNotFoundError, ValueError):\n        return {}\n\n\nstate = _State()\n\n\ndef step(name: str, fn, ttl: float = 7 * 86400) -> Any:\n    \"\"\"Run fn() once for this run and remember its (JSON) result: if the run\n    is retried after a failure, finished steps return their saved result\n    instead of running again. Use it around side effects (posting a reply,\n    charging a card) so a retry doesn't repeat them.\"\"\"\n    key = f\"step/{os.environ.get('CODIEDEV_RUN_ID', 'local')}/{name}\"\n    value, version = state.get_versioned(key)\n    if version:\n        return value[\"result\"]\n    result = fn()\n    state.set(key, {\"result\": result}, ttl=ttl)\n    return result\n\n\n_SELF = object()\n\n\ndef request_approval(\n    title: str,\n    details: Any = None,\n    options: \"list[str] | None\" = None,\n    approvers: \"list[str] | None\" = None,\n    teams: \"list[str] | None\" = None,\n    fields: \"list[dict] | None\" = None,\n    then: Any = _SELF,\n    context: Any = None,\n    expires_in: \"float | None\" = None,\n) -> dict:\n    \"\"\"Ask a person to decide. It shows in Codiedev (Agents → Approvals) and\n    at the returned [\"url\"], which you can post anywhere (Slack, email).\n\n    When it's decided, a run of `then` (this agent by default; None for no\n    run) starts with input {\"approval\": {\"decision\", \"comment\", \"decidedBy\",\n    ...}, \"context\": context}. If nobody decides within expires_in seconds\n    (default 7 days), it starts with decision \"expired\". Usually the run\n    ends after asking, so nothing runs (or costs) while it waits.\n    options default to [\"approve\", \"reject\"]; approvers (emails) and teams\n    (team names, e.g. [\"Finance\"]) limit who can decide (admins always can).\n    Apps your company connects (Agents → Approvals → Apps) are told about it\n    by webhook and can decide on a person's behalf.\n\n    fields asks the person to fill something in as they decide, e.g.\n    [{\"name\": \"rating\", \"type\": \"rating\"}, {\"name\": \"why\", \"type\": \"textarea\"}]\n    (types: text, textarea, number, rating, select, multiselect, boolean;\n    required, label, help, options, min, max, default). What they entered\n    arrives as input[\"approval\"][\"values\"]. With fields and no options, the\n    only choice is \"submit\".\"\"\"\n    body: dict = {\"title\": title, \"details\": details, \"options\": options, \"approvers\": approvers, \"teams\": teams, \"fields\": fields, \"context\": context}\n    if then is not _SELF:\n        body[\"onDecision\"] = then\n    if expires_in:\n        body[\"expiresSec\"] = int(expires_in)\n    if os.environ.get(\"CODIEDEV_LOCAL\") == \"1\":\n        print(f\"[local] approval requested: {title} ({', '.join(options or (['submit'] if fields else ['approve', 'reject']))}); not sent on a local run\", flush=True)\n        return {\"id\": f\"local-{int(time.time())}\", \"status\": \"pending\", \"url\": None, \"title\": title}\n    return _request(\"POST\", \"/api/agents/v1/approvals\", {k: v for k, v in body.items() if v is not None or k == \"onDecision\"})\n\n\ndef get_approval(approval_id: str) -> dict:\n    \"\"\"An approval's status (\"pending\", \"decided\", \"expired\"), decision and comment.\"\"\"\n    return _request(\"GET\", f\"/api/agents/v1/approvals?id={urllib.parse.quote(approval_id)}\")\n\n\ndef wait_for_approval(approval_id: str, timeout: float = 3600, poll: float = 15) -> dict:\n    \"\"\"Wait until a person decides (or it expires), then return the approval. For agents that keep\n    running while they wait, like a connected agent; a run inside Codiedev usually ends instead and\n    is started again with the decision.\"\"\"\n    deadline = time.time() + timeout\n    while True:\n        a = get_approval(approval_id)\n        if a.get(\"status\") != \"pending\":\n            return a\n        if time.time() > deadline:\n            raise TimeoutError(f\"approval {approval_id} still pending after {timeout}s\")\n        time.sleep(poll)\n\n\ndef openai(**kwargs):\n    \"\"\"An OpenAI client on the Codiedev gateway, with trace headers for this run.\"\"\"\n    from openai import OpenAI\n\n    headers = {\n        \"X-Codiedev-Workload\": os.environ.get(\"CODIEDEV_AGENT\", \"local-agent\"),\n        \"X-Codiedev-Run-Id\": os.environ.get(\"CODIEDEV_RUN_ID\", f\"local-{int(time.time())}\"),\n        \"X-Codiedev-Environment\": \"production\" if os.environ.get(\"CODIEDEV_RUN_ID\") else \"development\",\n    }\n    headers.update(kwargs.pop(\"default_headers\", {}) or {})\n    return OpenAI(\n        base_url=os.environ.get(\"CODIEDEV_GATEWAY_URL\", \"https://gateway.codiedev.com/api/v1\"),\n        api_key=os.environ.get(\"CODIEDEV_API_KEY\") or os.environ.get(\"CODIEDEV_TOKEN\"),\n        default_headers=headers,\n        **kwargs,\n    )\n";
+exports.jsIndex = "// Codiedev agents SDK for JavaScript and TypeScript, preinstalled in every\n// run. Same primitive as the Python SDK (codiedev_agents.py):\n//\n//   import * as agents from \"codiedev-agents\";\n//   const task = agents.input();                    // this run's input (JSON)\n//   const llm = await agents.openai();              // OpenAI client on the Codiedev gateway, traced\n//   const child = await agents.run(\"summarize\", { text });  // another agent, as a child run\n//   agents.output({ summary: child.output });       // this run's result\n//   agents.respond({ text: \"on it\" });              // what a webhook caller waiting (?wait=) gets back\n//   await agents.state.get(\"cursor\");               // per-agent storage that outlives runs\n//   await agents.step(\"post\", () => post());        // done once per run, even across retries\n//   await agents.start(\"triage\", input, { delaySec: 3600 });  // start a run later\n//   await agents.requestApproval(\"Refund $120?\", { context });  // a person decides; a run acts on it\n//\n// Outside a run, set CODIEDEV_TOKEN and CODIEDEV_AGENTS_URL and call run() the same way.\nimport fs from \"node:fs\";\nimport path from \"node:path\";\n\nconst INPUT_PATH = process.env.CODIEDEV_INPUT_PATH || \"/agent/.codiedev/input.json\";\nconst OUTPUT_PATH = process.env.CODIEDEV_OUTPUT_PATH || \"/agent/.codiedev/output.json\";\nconst REQUEST_PATH = process.env.CODIEDEV_REQUEST_PATH || \"/agent/.codiedev/request.json\";\nconst RESPONSE_PATH = process.env.CODIEDEV_RESPONSE_PATH || \"/agent/.codiedev/response.json\";\n// Set by `codiedev agents run --local`: state lives in this file instead of Codiedev.\nconst STATE_PATH = process.env.CODIEDEV_STATE_PATH;\n// Inside a run the run token picks the agent; a CLI token needs it named.\nconst AGENT = process.env.CODIEDEV_AGENT || \"\";\nconst DONE = new Set([\"succeeded\", \"failed\", \"cancelled\"]);\n\n/** state.set(..., { ifVersion }) found the key at another version. */\nexport class StateConflict extends Error {\n  constructor(key, version) {\n    super(`state ${JSON.stringify(key)} changed (now version ${version})`);\n    this.key = key;\n    this.version = version;\n  }\n}\n\nexport class AgentRunError extends Error {\n  constructor(run) {\n    super(`${run.agent} run ${run.id} ${run.status}: ${run.error || \"no error message\"}`);\n    this.run = run;\n  }\n}\n\nfunction readJson(file) {\n  try {\n    return JSON.parse(fs.readFileSync(file, \"utf8\"));\n  } catch (err) {\n    if (err.code === \"ENOENT\") return null;\n    throw err;\n  }\n}\n\n/** This run's input, parsed from JSON (`fallback` when started without one). */\nexport function input(fallback = null) {\n  const value = readJson(INPUT_PATH);\n  return value ?? fallback;\n}\n\n/** Set this run's result. Must be JSON-serializable; the last call wins. */\nexport function output(value) {\n  fs.mkdirSync(path.dirname(OUTPUT_PATH), { recursive: true });\n  fs.writeFileSync(OUTPUT_PATH, JSON.stringify(value));\n}\n\n/** What a webhook caller gets back when it waits for the run (?wait=N): a\n *  string is sent as text, anything else as JSON. Without it, a waiting\n *  caller gets the run's output. */\nexport function respond(body = null, { status = 200, headers = {} } = {}) {\n  fs.mkdirSync(path.dirname(RESPONSE_PATH), { recursive: true });\n  fs.writeFileSync(RESPONSE_PATH, JSON.stringify({ status, headers, body }));\n}\n\n/** This run's attempt: 1, or 2+ when it's a retry of a failed attempt. */\nexport function attempt() {\n  return Number(process.env.CODIEDEV_ATTEMPT || \"1\");\n}\n\n/** For a webhook run: { method, query, headers, body } with the raw body, to verify a signature. */\nexport function request() {\n  return readJson(REQUEST_PATH);\n}\n\nfunction base() {\n  const url = (process.env.CODIEDEV_AGENTS_URL || \"\").replace(/\\/$/, \"\");\n  if (!url) throw new Error(\"Set CODIEDEV_AGENTS_URL (it's set for you inside a run)\");\n  return url;\n}\n\nfunction token() {\n  // Inside a run: the run's token. A connected agent (running outside Codiedev): its own key.\n  // Otherwise: your CLI token.\n  const key = process.env.CODIEDEV_API_KEY || \"\";\n  const t = process.env.CODIEDEV_RUN_TOKEN || (key.startsWith(\"cdvm_\") ? key : \"\") || process.env.CODIEDEV_TOKEN;\n  if (!t) throw new Error(\"Set CODIEDEV_API_KEY to your connected agent's key, or CODIEDEV_TOKEN to your CLI token (inside a run it's set for you)\");\n  return t;\n}\n\nasync function call(method, route, body, ok = []) {\n  const res = await fetch(`${base()}${route}`, {\n    method,\n    headers: { Authorization: `Bearer ${token()}`, \"Content-Type\": \"application/json\" },\n    body: body === undefined ? undefined : JSON.stringify(body),\n  });\n  const text = await res.text();\n  let data = {};\n  try {\n    data = text ? JSON.parse(text) : {};\n  } catch {\n    data = { error: text };\n  }\n  if (ok.includes(res.status)) return { _status: res.status, ...data };\n  if (!res.ok) throw new Error(`Codiedev agents API ${res.status}: ${data.error || text}`);\n  return data;\n}\n\n/** Start a run and return its id without waiting. delaySec (up to 7 days)\n *  starts it later; retries overrides the agent's retries. */\nexport async function start(agent, input = null, { idempotencyKey, delaySec, retries } = {}) {\n  return (await call(\"POST\", \"/api/agents/v1/run\", {\n    agent,\n    input,\n    ...(idempotencyKey ? { idempotencyKey } : {}),\n    ...(delaySec ? { delaySec } : {}),\n    ...(retries !== undefined ? { retries } : {}),\n  })).runId;\n}\n\nfunction localState() {\n  try {\n    return JSON.parse(fs.readFileSync(STATE_PATH, \"utf8\"));\n  } catch {\n    return {};\n  }\n}\n\nasync function writeState(key, value, { ifVersion, ttlSec } = {}) {\n  if (STATE_PATH) {\n    const data = localState();\n    const current = data[key]?.version ?? 0;\n    if (ifVersion !== undefined && ifVersion !== current) throw new StateConflict(key, current);\n    if (value === null) delete data[key];\n    else data[key] = { value, version: current + 1 };\n    fs.writeFileSync(STATE_PATH, JSON.stringify(data, null, 2));\n    return value === null ? 0 : current + 1;\n  }\n  const res = await call(\"POST\", \"/api/agents/v1/state\", { key, value, agent: AGENT, ...(ifVersion !== undefined ? { ifVersion } : {}), ...(ttlSec ? { ttlSec } : {}) }, [409]);\n  if (res._status === 409) throw new StateConflict(key, res.version ?? 0);\n  return res.version ?? 0;\n}\n\n/** Per-agent key-value storage that outlives runs (values: any JSON, up to\n *  64 KB; 1,000 keys). Every write bumps the key's version; pass ifVersion\n *  to write only if nobody else did since you read it. */\nexport const state = {\n  async get(key, fallback = null) {\n    const { value } = await state.getVersioned(key);\n    return value ?? fallback;\n  },\n  /** { value, version }; { value: null, version: 0 } when the key isn't set. */\n  async getVersioned(key) {\n    if (STATE_PATH) {\n      const row = localState()[key];\n      return row ? { value: row.value, version: row.version } : { value: null, version: 0 };\n    }\n    const res = await call(\"GET\", `/api/agents/v1/state?${new URLSearchParams({ key, agent: AGENT })}`, undefined, [404]);\n    if (res._status === 404) return { value: null, version: 0 };\n    return { value: JSON.parse(res.value), version: res.version };\n  },\n  /** Store value; returns the new version. Throws StateConflict on an ifVersion mismatch (0 = unset). */\n  set(key, value, { ifVersion, ttlSec } = {}) {\n    return writeState(key, value, { ifVersion, ttlSec });\n  },\n  async delete(key, { ifVersion } = {}) {\n    await writeState(key, null, { ifVersion });\n  },\n  /** Keys (and with values: true, values) starting with prefix. */\n  async list(prefix = \"\", { values = false } = {}) {\n    if (STATE_PATH) {\n      return Object.entries(localState())\n        .filter(([k]) => k.startsWith(prefix))\n        .sort(([a], [b]) => a.localeCompare(b))\n        .map(([key, row]) => ({ key, version: row.version, ...(values ? { value: row.value } : {}) }));\n    }\n    const out = [];\n    let after = null;\n    do {\n      const q = new URLSearchParams({ prefix, values: values ? \"1\" : \"0\", limit: \"200\", agent: AGENT, ...(after ? { after } : {}) });\n      const page = await call(\"GET\", `/api/agents/v1/state?${q}`);\n      out.push(...page.keys.map((row) => (\"value\" in row ? { ...row, value: JSON.parse(row.value) } : row)));\n      after = page.next;\n    } while (after);\n    return out;\n  },\n  /** Read-modify-write that's safe with runs in parallel: fn(old) => new, retried if another run wrote first. */\n  async update(key, fn, fallback = null, retries = 10) {\n    for (let i = 0; i < retries; i++) {\n      const { value, version } = await state.getVersioned(key);\n      const next = await fn(value ?? fallback);\n      try {\n        await state.set(key, next, { ifVersion: version });\n        return next;\n      } catch (err) {\n        if (!(err instanceof StateConflict)) throw err;\n        await new Promise((resolve) => setTimeout(resolve, 50));\n      }\n    }\n    throw new StateConflict(key, -1);\n  },\n};\n\n/** Run fn() once for this run and remember its (JSON) result: if the run is\n *  retried after a failure, finished steps return their saved result instead\n *  of running again. Use it around side effects so a retry doesn't repeat them. */\nexport async function step(name, fn, { ttlSec = 7 * 86400 } = {}) {\n  const key = `step/${process.env.CODIEDEV_RUN_ID || \"local\"}/${name}`;\n  const { value, version } = await state.getVersioned(key);\n  if (version) return value.result;\n  const result = await fn();\n  await state.set(key, { result: result ?? null }, { ttlSec });\n  return result;\n}\n\n/** Ask a person to decide. It shows in Codiedev (Agents → Approvals) and at\n *  the returned .url, which you can post anywhere. When it's decided, a run of\n *  `then` (this agent by default; null for none) starts with input\n *  { approval: { decision, comment, decidedBy, ... }, context }. Undecided\n *  after expiresSec (default 7 days): decision \"expired\". */\nexport async function requestApproval(title, { details, options, approvers, teams, fields, then, context, expiresSec } = {}) {\n  if (process.env.CODIEDEV_LOCAL === \"1\") {\n    console.log(`[local] approval requested: ${title} (${(options || (fields ? [\"submit\"] : [\"approve\", \"reject\"])).join(\", \")}); not sent on a local run`);\n    return { id: `local-${Date.now()}`, status: \"pending\", url: null, title };\n  }\n  return call(\"POST\", \"/api/agents/v1/approvals\", {\n    title,\n    ...(details !== undefined ? { details } : {}),\n    ...(options ? { options } : {}),\n    ...(approvers ? { approvers } : {}),\n    ...(teams ? { teams } : {}),\n    ...(fields ? { fields } : {}),\n    ...(then !== undefined ? { onDecision: then } : {}),\n    ...(context !== undefined ? { context } : {}),\n    ...(expiresSec ? { expiresSec } : {}),\n  });\n}\n\n/** An approval's status (\"pending\", \"decided\", \"expired\"), decision and comment. */\nexport async function getApproval(id) {\n  return call(\"GET\", `/api/agents/v1/approvals?id=${encodeURIComponent(id)}`);\n}\n\n/** Wait until a person decides (or it expires), then return the approval. For agents that keep\n *  running while they wait, like a connected agent; a run inside Codiedev usually ends instead and\n *  is started again with the decision. */\nexport async function waitForApproval(id, { timeoutMs = 3_600_000, pollMs = 15_000 } = {}) {\n  const deadline = Date.now() + timeoutMs;\n  for (;;) {\n    const a = await getApproval(id);\n    if (a.status !== \"pending\") return a;\n    if (Date.now() > deadline) throw new Error(`approval ${id} still pending after ${timeoutMs / 1000}s`);\n    await new Promise((resolve) => setTimeout(resolve, pollMs));\n  }\n}\n\n/** A run's status, input, output (parsed), error, log and children. */\nexport async function get(runId) {\n  const run = await call(\"GET\", `/api/agents/v1/run?id=${encodeURIComponent(runId)}`);\n  if (typeof run.output === \"string\") {\n    try {\n      run.output = JSON.parse(run.output);\n    } catch {\n      // not JSON: keep the string\n    }\n  }\n  return run;\n}\n\n/** Run an agent and wait for it; its result is `.output`. Inside a run this\n *  starts a child run. Throws AgentRunError if it fails unless check is false. */\nexport async function run(agent, input = null, { timeoutMs = 900_000, pollMs = 2000, check = true, idempotencyKey } = {}) {\n  const id = await start(agent, input, { idempotencyKey });\n  const deadline = Date.now() + timeoutMs;\n  for (;;) {\n    const r = await get(id);\n    if (DONE.has(r.status)) {\n      if (check && r.status !== \"succeeded\") throw new AgentRunError(r);\n      return r;\n    }\n    if (Date.now() > deadline) throw new Error(`${agent} run ${id} still ${r.status} after ${timeoutMs / 1000}s`);\n    await new Promise((resolve) => setTimeout(resolve, pollMs));\n  }\n}\n\n/** Options for `new OpenAI(...)` on the Codiedev gateway, with this run's trace headers. */\nexport function openaiOptions(extra = {}) {\n  const inRun = !!process.env.CODIEDEV_RUN_ID;\n  return {\n    baseURL: process.env.CODIEDEV_GATEWAY_URL || \"https://gateway.codiedev.com/api/v1\",\n    apiKey: process.env.CODIEDEV_API_KEY || process.env.CODIEDEV_TOKEN,\n    ...extra,\n    defaultHeaders: {\n      \"X-Codiedev-Workload\": process.env.CODIEDEV_AGENT || \"local-agent\",\n      \"X-Codiedev-Run-Id\": process.env.CODIEDEV_RUN_ID || `local-${Date.now()}`,\n      \"X-Codiedev-Environment\": inRun ? \"production\" : \"development\",\n      ...(extra.defaultHeaders || {}),\n    },\n  };\n}\n\n/** An OpenAI client on the Codiedev gateway (the `openai` package is preinstalled). */\nexport async function openai(extra = {}) {\n  const { default: OpenAI } = await import(\"openai\");\n  return new OpenAI(openaiOptions(extra));\n}\n";
+exports.jsTypes = "/* eslint-disable @typescript-eslint/no-explicit-any -- defaults are `any` on purpose: agent code reads its own JSON input/state without declaring types first. */\nexport type RunStatus = \"queued\" | \"running\" | \"succeeded\" | \"failed\" | \"cancelled\";\nexport interface Run<O = unknown> {\n  id: string;\n  agent: string;\n  version: number;\n  status: RunStatus;\n  trigger: \"cli\" | \"api\" | \"portal\" | \"schedule\" | \"webhook\" | \"child\" | \"approval\";\n  parentRunId: string | null;\n  rootRunId: string | null;\n  depth: number;\n  attempt: number;\n  maxAttempts: number;\n  scheduledFor: number | null;\n  input: string | null;\n  output: O;\n  error: string | null;\n  logTail: string | null;\n  durationMs: number | null;\n  children: Run[];\n}\nexport interface WebhookRequest { method: string; query: Record<string, string>; headers: Record<string, string>; body: string }\nexport interface Approval {\n  id: string;\n  agent: string;\n  title: string;\n  details: string | null;\n  options: string[];\n  status: \"pending\" | \"decided\" | \"expired\" | \"cancelled\";\n  decision: string | null;\n  comment: string | null;\n  decidedBy: string | null;\n  /** The approval app that sent the decision on decidedBy's behalf; null when decided in Codiedev. */\n  decidedVia: string | null;\n  approvers: string[];\n  approverTeams: Array<{ id: string; name: string }>;\n  /** The form the person fills in, if the approval asked for one. */\n  fields: ApprovalField[];\n  /** What they entered, by field name (null until decided). */\n  values: Record<string, any> | null;\n  url: string | null;\n  resumeRunId: string | null;\n}\n/** One thing a person fills in when they decide. */\nexport interface ApprovalField {\n  name: string;\n  type: \"text\" | \"textarea\" | \"number\" | \"rating\" | \"select\" | \"multiselect\" | \"boolean\";\n  label?: string;\n  help?: string;\n  required?: boolean;\n  /** select / multiselect choices */\n  options?: string[];\n  /** number bounds; rating scale 1–max (default 5) */\n  min?: number;\n  max?: number;\n  /** prefilled, e.g. a proposed amount for the person to correct */\n  default?: unknown;\n}\n/** The input a run started by a decision gets. */\nexport interface ApprovalInput<C = any, V = Record<string, any>> {\n  approval: { id: string; title: string; decision: string; comment: string | null; values: V; decidedBy: string | null; decidedVia: string | null; decidedAt: number; requestedByRun: string | null };\n  context: C;\n}\nexport class AgentRunError extends Error { run: Run }\nexport class StateConflict extends Error { key: string; version: number }\nexport function input<T = any>(fallback?: T): T;\nexport function output(value: unknown): void;\nexport function request(): WebhookRequest | null;\nexport function respond(body?: unknown, opts?: { status?: number; headers?: Record<string, string> }): void;\nexport function attempt(): number;\nexport function start(agent: string, input?: unknown, opts?: { idempotencyKey?: string; delaySec?: number; retries?: number }): Promise<string>;\nexport function get<O = any>(runId: string): Promise<Run<O>>;\nexport function run<O = any>(agent: string, input?: unknown, opts?: { timeoutMs?: number; pollMs?: number; check?: boolean; idempotencyKey?: string }): Promise<Run<O>>;\nexport const state: {\n  get<T = any>(key: string, fallback?: T): Promise<T>;\n  getVersioned<T = any>(key: string): Promise<{ value: T | null; version: number }>;\n  set(key: string, value: unknown, opts?: { ifVersion?: number; ttlSec?: number }): Promise<number>;\n  delete(key: string, opts?: { ifVersion?: number }): Promise<void>;\n  list(prefix?: string, opts?: { values?: boolean }): Promise<Array<{ key: string; version: number; value?: any }>>;\n  update<T = any>(key: string, fn: (old: T) => T | Promise<T>, fallback?: T, retries?: number): Promise<T>;\n};\nexport function step<T>(name: string, fn: () => T | Promise<T>, opts?: { ttlSec?: number }): Promise<T>;\nexport function requestApproval<C = any>(title: string, opts?: { details?: unknown; options?: string[]; approvers?: string[]; teams?: string[]; fields?: ApprovalField[]; then?: string | null; context?: C; expiresSec?: number }): Promise<Approval>;\nexport function getApproval(id: string): Promise<Approval>;\nexport function waitForApproval(id: string, opts?: { timeoutMs?: number; pollMs?: number }): Promise<Approval>;\nexport function openaiOptions(extra?: Record<string, unknown>): { baseURL: string; apiKey: string | undefined; defaultHeaders: Record<string, string> };\nexport function openai(extra?: Record<string, unknown>): Promise<import(\"openai\").default>;";
+exports.jsPackage = "{\n  \"name\": \"codiedev-agents\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Codiedev agents SDK: this run's input and output, chaining, and a traced OpenAI client.\",\n  \"type\": \"module\",\n  \"main\": \"./index.mjs\",\n  \"types\": \"./index.d.ts\",\n  \"exports\": { \".\": { \"types\": \"./index.d.ts\", \"default\": \"./index.mjs\" } }\n}\n";

package/dist/commands/ask.js

@@ -3,9 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runAsk = runAsk;
 const shared_1 = require("./shared");
 function parseArgs(args) {
-    // Everything after the command, joined back into a question string. Allows
-    // both quoted and unquoted forms: `codiedev ask "why pg-bouncer?"` or
-    // `codiedev ask why did we drop pg-bouncer`.
     const question = args
         .filter((a) => !a.startsWith("--"))
         .join(" ")

package/dist/commands/capture.js

@@ -123,7 +123,6 @@ async function runCaptureCommand(args, depsOverride = {}) {
         return;
     }
     if (subcommand === "ignored") {
-        // `ignored` lists everything; `ignored <path>` answers "is this ignored?".
         const query = args.slice(1).join(" ").trim();
         if (query) {
             reportCheck(query, current, deps);
@@ -139,7 +138,6 @@ async function runCaptureCommand(args, depsOverride = {}) {
             deps.log(`  ${value}`);
         return;
     }
-    // Back-compat: the earlier `codiedev capture check <path>` form.
     if (subcommand === "check") {
         reportCheck(requirePath(args), current, deps);
         return;

package/dist/commands/createTicket.js

@@ -100,7 +100,6 @@ async function runCreateTicket(args) {
         await runBare(config, parsed.prompt);
         return;
     }
-    // submit mode
     if (!parsed.submitSource) {
         console.error("--submit requires a path or '-' for stdin");
         process.exit(1);
@@ -114,7 +113,6 @@ async function runCreateTicket(args) {
         console.error(`Failed to read plan: ${err.message}`);
         process.exit(1);
     }
-    // Translate fullNames → IDs before submitting
     let parsedPlan;
     try {
         parsedPlan = JSON.parse(raw);
@@ -141,14 +139,6 @@ async function runCreateTicket(args) {
     }
     await runSubmit(config, JSON.stringify(parsedPlan));
 }
-/**
- * Bare-mode entrypoint. Fetches the protocol body from the backend so we can
- * iterate on it without shipping a new CLI, substitutes the user's prompt,
- * and writes the result to stdout for the agent to follow. Hard-errors on
- * fetch failure rather than falling back to a stale local copy — the whole
- * point of moving the protocol server-side is that the freshest version is
- * the only version.
- */
 async function runBare(config, prompt) {
     let res;
     try {

package/dist/commands/doctor.js

@@ -81,12 +81,6 @@ function codexInstalled() {
 function cursorInstalled() {
     return fs.existsSync(path.join(os.homedir(), ".cursor"));
 }
-// `isCodiedevHookCommand` lives in ../detection alongside detectClaudeCode
-// so utils.ts and doctor.ts share one definition (they used to drift —
-// each had its own copy).
-// Cursor's hooks.json schema is { hooks: { sessionEnd: [{ command, ... }] } }
-// — flat array of objects with `command`, not the Claude/Codex nested
-// `{ hooks: [{ command }] }` wrapper.
 function hasCursorHook() {
     try {
         if (!fs.existsSync(CURSOR_HOOKS_PATH))
@@ -137,7 +131,6 @@ async function runDoctor(_args) {
     const checks = [];
     console.log("\nCodiedev doctor — checking your setup…\n");
     await (0, upgradeNudge_1.maybePrintUpgradeNudge)();
-    // 1. Config file
     const config = (0, utils_1.readConfig)();
     if (!config) {
         checks.push({
@@ -153,19 +146,12 @@ async function runDoctor(_args) {
         status: "pass",
         detail: `connected to ${config.companyName}`,
     });
-    // 2. Token still valid + backend reachable (re-validate). The detail names
-    // the backend host so users (and their IT) can confirm which domain the CLI
-    // talks to — the same host capture uploads use, so this check exercises the
-    // exact TLS path a corporate proxy would intercept.
     let backendHost = "the capture host";
     try {
         backendHost = new URL(config.backendUrl).host;
     }
     catch {
-        // malformed backendUrl in config — keep the generic placeholder
     }
-    // Live tracked-repo list fetched from validateToken below. Null until (and
-    // unless) the backend answers; the checks fall back to `config.repos`.
     let liveRepos = null;
     try {
         const res = await fetch(`${config.backendUrl}/api/cli/validateToken`, {
@@ -182,20 +168,13 @@ async function runDoctor(_args) {
                 status: "pass",
                 detail: backendHost,
             });
-            // validateToken returns the company's CURRENT tracked repos. Capture
-            // them: the repo-resolution checks below must reflect what the SERVER
-            // will resolve at capture time (repoResolver.ts resolves against the
-            // live list), not the possibly-stale `config.repos` frozen at the last
-            // `connect`. A repo linked in the portal after that connect otherwise
-            // reports a false "isn't a tracked repo — link it in the portal" here
-            // even though sessions/MRs for it attribute fine server-side.
             try {
                 const data = (await res.json());
                 if (Array.isArray(data.repos))
                     liveRepos = data.repos;
             }
             catch {
-                liveRepos = null; // malformed body → fall back to the cached list
+                liveRepos = null;
             }
         }
         else {
@@ -207,9 +186,6 @@ async function runDoctor(_args) {
         }
     }
     catch (err) {
-        // fetch buries the real TLS/socket error in .cause ("fetch failed" alone
-        // is undiagnosable); unwrap it and, when it's an SSL-inspection signature,
-        // say what actually fixes it.
         const desc = (0, captureReadiness_1.describeFetchError)(err);
         const tlsHint = (0, captureReadiness_1.tlsInterceptionHint)(desc, backendHost);
         checks.push({
@@ -218,7 +194,6 @@ async function runDoctor(_args) {
             detail: tlsHint ? `${desc} — ${tlsHint}` : `${desc} (host: ${backendHost})`,
         });
     }
-    // 3. Authenticated endpoint smoke test (inbox query)
     try {
         await (0, shared_1.apiRequest)("GET", "/api/cli/inbox", {
             config,
@@ -236,38 +211,16 @@ async function runDoctor(_args) {
             detail: err.message,
         });
     }
-    // 4. Tracked repos. Prefer the live list from validateToken over the cache:
-    // a repo linked after the last `connect` is tracked server-side but absent
-    // from `config.repos`, and resolving against the stale cache is exactly what
-    // produced the false "isn't a tracked repo — link it in the portal" warning.
-    // Treat an EMPTY live list as "no usable live data", NOT an authoritative
-    // zero: a transient permission glitch / backend hiccup can return `repos: []`,
-    // and both driving the checks from it AND healing the cache to empty would be
-    // wrong — the write would durably break every offline doctor run (and the
-    // capture hook's providedRepoId) until the next successful connect. So when
-    // live is empty, fall back to the cache and skip the write, exactly like
-    // backend-unreachable. A genuinely repo-less company also has an empty cache,
-    // so it still reports "0 repos" correctly.
     const trackedRepos = liveRepos !== null && liveRepos.length > 0 ? liveRepos : (config.repos ?? []);
-    // Detect drift by CONTENT, not count: a same-size swap (one repo removed +
-    // another added between connects) or a repo whose path/URL changed while its
-    // id stayed stable (GitLab move/rename — exactly the SONIFI migration case)
-    // both leave the count unchanged. A length-only check would skip the heal and
-    // leave the capture hook's cache — and its advisory providedRepoId — stale.
     const canonRepos = (rs) => JSON.stringify([...rs].map((r) => [r.repoId, r.url, r.fullName]).sort());
     const cacheRefreshed = liveRepos !== null &&
         liveRepos.length > 0 &&
         canonRepos(liveRepos) !== canonRepos(config.repos ?? []);
-    // Heal the on-disk cache so the capture hook (which reads `config.repos` for
-    // the advisory providedRepoId) stops trailing the portal too. Best-effort:
-    // doctor must never fail because the config couldn't be rewritten.
     if (cacheRefreshed && liveRepos) {
         try {
             (0, utils_1.writeConfig)({ ...config, repos: liveRepos, lastSynced: new Date().toISOString() });
         }
         catch {
-            // read-only home / permission issue — the in-memory list still drives
-            // the checks below; the user just re-syncs on the next `connect`.
         }
     }
     const repoCount = trackedRepos.length;
@@ -278,11 +231,6 @@ async function runDoctor(_args) {
             ? `${repoCount} repo${repoCount === 1 ? "" : "s"}${cacheRefreshed ? " (refreshed from portal)" : ""}`
             : "0 — link repos in the portal so sessions get captured",
     });
-    // 4b. Capture readiness — the part that actually decides whether a session
-    // lands. doctor used to verify only that the hook was *installed*; these
-    // checks answer "from this directory, would a session capture, and did my
-    // last one?" — the blind spot behind lean-container / submodule / no-remote
-    // zeros.
     const cwd = process.cwd();
     const readiness = (0, captureReadiness_1.assessCaptureReadiness)(cwd, trackedRepos, {
         exec: (cmd, dir) => (0, child_process_1.execSync)(cmd, { cwd: dir, stdio: ["pipe", "pipe", "pipe"] }).toString(),
@@ -291,11 +239,6 @@ async function runDoctor(_args) {
         getBranch: utils_1.getGitBranch,
         getHeadSha: utils_1.getGitHeadSha,
     });
-    // Workspace-root mode: the cwd isn't a repo itself, but git repos sit
-    // directly under it (one `.devcontainer/` at a parent folder of several
-    // cloned repos). Capture tags the sub-repo a session edits, so report that
-    // instead of flatly warning "not a work tree / no remote" — the exact output
-    // that made working workspace-root setups read as broken.
     const workspaceScan = readiness.gitOnPath && !readiness.insideWorkTree
         ? (0, captureReadiness_1.assessWorkspaceRepos)(cwd, trackedRepos, {
             listChildDirs: (dir) => fs
@@ -310,8 +253,6 @@ async function runDoctor(_args) {
     const workspaceMode = workspaceScan.repoCount > 0;
     checks.push({
         name: "git on PATH",
-        // A warning, not a failure: sessions still capture without git, they just
-        // aren't tagged to a repo. Non-engineer installs often skip git entirely.
         status: readiness.gitOnPath ? "pass" : "warn",
         detail: readiness.gitOnPath
             ? undefined
@@ -348,9 +289,6 @@ async function runDoctor(_args) {
                 ? "branch/sha resolve from the sub-repo each session writes to"
                 : "no branch/sha resolved — session→merge attribution will be weaker",
     });
-    // 4c. The payoff: did the last session actually land? Ask the server for
-    // portal truth (does the row exist for this user?), falling back to the local
-    // 2xx breadcrumb if the endpoint is unreachable or predates this CLI/backend.
     const localMarker = (0, utils_1.readLastCapture)();
     let server = null;
     try {
@@ -371,7 +309,7 @@ async function runDoctor(_args) {
             server = (await res.json());
     }
     catch {
-        server = null; // unreachable / old backend → fall back to the local marker
+        server = null;
     }
     const lastCapture = (0, captureReadiness_1.summarizeServerCapture)(server, localMarker, Date.now());
     checks.push({
@@ -379,7 +317,6 @@ async function runDoctor(_args) {
         status: lastCapture.status,
         detail: lastCapture.detail,
     });
-    // 4d. Capture-log activity: did recent uploads succeed? Are there pending jobs?
     const logTail = (0, captureLog_1.readCaptureLogTail)(40);
     let pendingJobCount = 0;
     try {
@@ -396,17 +333,12 @@ async function runDoctor(_args) {
         status: captureActivity.status,
         detail: captureActivity.detail,
     });
-    // 5. Claude Code setup (if present)
     if ((0, utils_1.claudeCodeInstalled)()) {
         checks.push({
             name: "Claude Code detected",
             status: "pass",
             detail: (0, harnessDirs_1.displayPath)(CLAUDE_DIR),
         });
-        // A hook in settings.json only fires if Claude Code actually reads this
-        // dir. If it holds nothing Claude Code writes on use, it's running from
-        // somewhere else (CLAUDE_CONFIG_DIR unset in this shell, another user,
-        // the host vs. a container) and the ✓s below are hollow.
         checks.push(configDirInUseCheck("Claude Code", CLAUDE_DIR, (0, harnessDirs_1.claudeConfigDirInUse)(CLAUDE_DIR), "CLAUDE_CONFIG_DIR"));
         checks.push({
             name: "Claude Code SessionEnd hook",
@@ -430,7 +362,6 @@ async function runDoctor(_args) {
             detail: "not installed on this machine",
         });
     }
-    // 6. Codex setup (if present)
     if (codexInstalled()) {
         checks.push({
             name: "Codex detected",
@@ -460,7 +391,6 @@ async function runDoctor(_args) {
             detail: "not installed on this machine",
         });
     }
-    // 7. Cursor setup (if present)
     if (cursorInstalled()) {
         checks.push({
             name: "Cursor detected",

package/dist/commands/evals.js

@@ -1,13 +1,4 @@
 "use strict";
-// `codiedev evals report <run.json> [--harness name]`
-// `codiedev evals last <subject> [--json]`
-//
-// Evals are experiments (a question about a subject: an agent, or a workload
-// like session-summaries) and the runs that answer them, one per variant. The
-// eval runs wherever it runs (a script, a coding agent); `report` files the
-// scores under the experiment in Codiedev → Traces → Evals, shared with the
-// team. `last` is where to start the next one: the latest experiment on the
-// subject, its runs, and the champion the subject runs today.
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -67,6 +58,7 @@ codiedev evals — experiments and their runs, shared with the team
       "provider": "openai", "reasoningEffort": "medium", "prompt": "summary_extract_v2",
       "gitSha": "…", "isControl": false, "judgeModel": "anthropic/claude-sonnet-5.5",
       "casesTotal": 30, "casesScored": 30, "errors": 0,
+      "scoringRevision": 1,                   // required once experiment scoring rules are defined
       "score": 3.85, "metrics": { "fidelity": 3.6 },
       "costPerCaseUsd": 0.026, "latencyMsAvg": 21000,
       "wins": 20, "losses": 8, "ties": 2, "note": "…",
@@ -74,6 +66,8 @@ codiedev evals — experiments and their runs, shared with the team
     }
   }
 
+  Read scoring rules and their current revision with: codiedev evals last <subject> --json
+
   Scores and notes only: never put prompts, transcripts or outputs in it.
 `.trim();
 function flag(args, i, name) {

package/dist/commands/inbox.js

@@ -70,8 +70,6 @@ async function runRead(args) {
     const config = (0, shared_1.requireConfig)();
     const start = Date.now();
     try {
-        // First, fetch inbox so we can show the full body (markRead endpoint
-        // doesn't return content).
         const listRes = await (0, shared_1.apiRequest)("GET", "/api/cli/inbox", {
             config,
             query: { limit: 100 },

package/dist/commands/library.js

@@ -1,7 +1,4 @@
 "use strict";
-// `codiedev library [--scope mine|shared|all] [--kind doc|skill] [--tag X]
-// [--type spec|...] [--limit N]` — list artifacts in your Codiedev workspace.
-// Server applies companyId scoping; --scope filters within that.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runLibrary = runLibrary;
 const shared_1 = require("./shared");

package/dist/commands/pack.js

@@ -59,10 +59,7 @@ const harnesses_2 = require("../packs/harnesses");
 const os = __importStar(require("os"));
 const utils_1 = require("../utils");
 const shared_1 = require("./shared");
-// --- CI (pack-scoped `cdvci_` keys) ------------------------------------------
 exports.DEFAULT_BACKEND_URL = "https://cli.codiedev.com";
-/** CODIEDEV_TOKEN alone is enough: no ~/.codiedev/config.json needed (CI).
- * CODIEDEV_URL defaults to production. Otherwise the connected config. */
 function resolvePackConfig(env = process.env) {
     const token = env.CODIEDEV_TOKEN?.trim();
     if (token) {
@@ -78,8 +75,6 @@ function resolvePackConfig(env = process.env) {
     const config = (0, utils_1.readConfig)();
     return config ? (0, shared_1.applyConfigEnvOverrides)(config) : null;
 }
-/** In CI, `--harness` defaults to claude when it's on PATH; anything else is
- * ambiguous on a build box, so say what was found. */
 function ciHarnesses(args, env, home) {
     if (args.harnesses?.length)
         return args.harnesses;
@@ -223,8 +218,6 @@ async function runInstall(config, args, overrides = {}) {
     const ci = (0, sync_1.isPackCiMode)(overrides.env ?? process.env);
     const harnesses = ci && !args.dryRun ? ciHarnesses(args, overrides.env ?? process.env, overrides.home) : args.harnesses;
     const listed = args.slug ? [args.slug] : (await listPacks(config)).map((p) => p.slug);
-    // With no slug, also re-check every locally installed pack: one that was
-    // unassigned or archived 404s and must be removed locally. Not in CI: no pruning.
     const slugs = args.slug || ci ? listed : [...new Set([...listed, ...Object.keys(registry.packs)])];
     const manifests = [];
     const revoked = [];
@@ -241,7 +234,6 @@ async function runInstall(config, args, overrides = {}) {
                 revoked.push(slug);
             else if (args.slug)
                 throw new Error(`Pack not found or not assigned to your team: ${slug}`);
-            // A listed pack that 404s a moment later (race with an unassign) is skipped.
         }
     }
     let installed = manifests.length
@@ -249,8 +241,6 @@ async function runInstall(config, args, overrides = {}) {
         : [];
     let removed = [];
     if (!args.dryRun && !ci) {
-        // A 404 on the installed report means the pack stopped applying between
-        // the manifest fetch and now: treat it exactly like a revoked pack.
         const lateRevoked = await reportInstalled(config, installed);
         installed = installed.filter((p) => !lateRevoked.includes(p.slug));
         removed = await removePacks(config, [...revoked, ...lateRevoked], overrides);
@@ -285,11 +275,7 @@ async function runInstall(config, args, overrides = {}) {
         for (const line of (0, install_1.formatUninstallLines)(removed))
             console.log(line);
     }
-    // Exit non-zero when a pack reached no tool because of a failure, or the
-    // pack explicitly asked for is no longer available.
     const failed = installed.some((p) => p.results.some((r) => r.status === "failed") && !p.results.some((r) => r.status === "ok"));
-    // CI is strict: every requested tool must have taken every pack, and there
-    // must have been a pack to install at all.
     const ciFailed = ci && !args.dryRun && (installed.length === 0 || installed.some((p) => p.results.some((r) => r.status !== "ok")));
     if (ci && !args.dryRun && installed.length === 0)
         console.error("No pack is visible to this key.");
@@ -297,8 +283,6 @@ async function runInstall(config, args, overrides = {}) {
         process.exitCode = 1;
     return run;
 }
-/** POST each install. Returns slugs the server answered 404 for (revoked);
- * any other failure is only a warning. */
 async function reportInstalled(config, results) {
     const revoked = [];
     for (const pack of results) {
@@ -317,7 +301,6 @@ async function reportInstalled(config, results) {
     }
     return revoked;
 }
-/** Uninstall packs locally, then tell the server (best-effort, idempotent). */
 async function removePacks(config, slugs, overrides) {
     if (slugs.length === 0)
         return [];
@@ -365,7 +348,6 @@ async function runStatus(config, json, overrides = {}, options = {}) {
         }
         rows.push({ slug, ...entry, upToDate, latestVersion, latestChannel });
     }
-    // --no-prune (background check when auto-update is off) and CI: report only.
     const ci = (0, sync_1.isPackCiMode)(overrides.env ?? process.env);
     const removed = options.prune === false || ci ? [] : await removePacks(config, revoked, overrides);
     if (available && !ci) {
@@ -414,9 +396,7 @@ async function runPack(args) {
     }
     const config = resolvePackConfig() ?? (0, shared_1.requireConfig)();
     const ci = (0, sync_1.isPackCiMode)();
-    // --quiet (the background auto-update): no output at all.
     const restore = parsed.quiet ? silenceConsole() : () => { };
-    // CI keys can only read packs: no telemetry POST either.
     const track = ci ? (_c, _t, fn) => fn() : shared_1.withTelemetry;
     try {
         await track(config, `codiedev_pack_${parsed.sub === "ls" ? "list" : parsed.sub}`, async () => {
@@ -449,13 +429,10 @@ function silenceConsole() {
         console.error = error;
     };
 }
-// --- pack export / apply ---------------------------------------------------
 function gitIn(dir, args) {
     const r = (0, child_process_1.spawnSync)("git", args, { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
     return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? (r.error?.message ?? "") };
 }
-/** Init (if needed) and commit everything under `dir`. Uses the user's git
- * identity when configured, a neutral Codiedev one otherwise (fresh CI). */
 function commitExport(dir, message) {
     if (!fs.existsSync(path.join(dir, ".git"))) {
         const init = gitIn(dir, ["init", "-q"]);
@@ -491,9 +468,6 @@ function readMarketplaceEntries(dir) {
         return [];
     }
 }
-/** Write a CI-committable copy of the pack: `<out>/plugins/<slug>/…` plus
- * `<out>/.claude-plugin/marketplace.json` (existing entries for other packs
- * in the same folder are kept). */
 function exportPluginFolder(out, manifest) {
     fs.mkdirSync(out, { recursive: true });
     const dir = (0, store_1.writePluginDir)(out, manifest);
@@ -522,7 +496,6 @@ async function runExport(config, args) {
         if (typeof res.markdown !== "string")
             throw new Error("Server returned no markdown");
         fs.mkdirSync(out, { recursive: true });
-        // <slug>.pack.md so several packs can share one folder.
         written = path.join(out, `${args.slug}.pack.md`);
         (0, store_1.writeFileAtomic)(written, res.markdown.endsWith("\n") ? res.markdown : `${res.markdown}\n`);
         message = `codiedev pack export ${args.slug} (${args.slug}.pack.md)`;
@@ -576,8 +549,6 @@ async function runApply(config, args) {
         res = await (0, shared_1.apiRequest)("POST", "/api/cli/packs/apply", { config, body: { markdown } });
     }
     catch (error) {
-        // The server reports pack.md problems with line numbers; show them as-is.
-        // The server's 400 is already "pack.md line N: …" — print it verbatim.
         const e = error;
         if (e.status === 403)
             throw new Error(`You can't edit this pack (${e.message})`);

package/dist/commands/ping.js

@@ -23,8 +23,6 @@ function parseArgs(args) {
         process.exit(1);
     }
     to = positional[0];
-    // Join remaining positionals in case the shell split the message on spaces
-    // despite quoting (happens with some escape sequences).
     const body = (0, shared_1.stripQuotes)(positional.slice(1).join(" "));
     return { to, body, subjectKey };
 }

package/dist/commands/pull.js

@@ -71,10 +71,6 @@ function parseArgs(args) {
     }
     return { key, version, out };
 }
-// The backend stores skills under extension-bearing keys (e.g. "pr-push.md"),
-// and lookup is exact-match, so a bare "pr-push" 404s. Make pull forgiving: try
-// the key as given, then a ".md" fallback when it has no extension, so the
-// intuitive bare name (and the hook's suggested key) both resolve.
 function candidateKeys(key) {
     if (/\.[a-z0-9]+$/i.test(key))
         return [key];
@@ -97,16 +93,12 @@ async function runPull(args) {
             }
             catch (err) {
                 const e = err;
-                // A 404 on a non-final candidate is retryable (fall through to ".md");
-                // anything else — or the last candidate — propagates to the handler.
                 if (e.status === 404 && i < keys.length - 1)
                     continue;
                 throw err;
             }
         }
         const a = res.artifact;
-        // A skill carries its identity onto disk so its runs attribute exactly
-        // (see skillMarker.ts). Docs are written verbatim.
         const isSkill = a.kind ? a.kind === "skill" : (0, skillMarker_1.looksLikeSkill)(a.markdown);
         const markdown = isSkill ? (0, skillMarker_1.stampSkillMarker)(a.markdown, a._id) : a.markdown;
         (0, shared_1.recordAgentEvent)(config, {
@@ -123,7 +115,6 @@ async function runPull(args) {
             console.log(`  updated:   ${(0, shared_1.timeAgo)(a.updatedAt ?? a.createdAt)}`);
         }
         else {
-            // Stream to stdout — preserves shell pipes like `codiedev pull spec-214.md | less`.
             process.stdout.write(markdown);
             if (!markdown.endsWith("\n"))
                 process.stdout.write("\n");

package/dist/commands/push.js

@@ -107,10 +107,6 @@ function parseArgs(args) {
         console.error(`Invalid --kind. Valid kinds: ${[...VALID_KINDS].join(", ")}`);
         process.exit(1);
     }
-    // The override key is stored verbatim by the server (docs key off it, and a
-    // path-y value like "specs/feature-a/plan.md" populates folderPath). Strip a
-    // leading slash so it can't be confused with an absolute path, and reject an
-    // empty value — but otherwise allow slashes so callers can namespace.
     if (as !== undefined) {
         as = as.replace(/^\/+/, "").trim();
         if (!as) {
@@ -121,7 +117,6 @@ function parseArgs(args) {
     return { file, type, kind, tags, force, as, private: priv };
 }
 async function pushFile(config, opts) {
-    // Never upload another artifact's identity marker (skillMarker.ts).
     const markdown = (0, skillMarker_1.stripSkillMarker)(fs.readFileSync(opts.absPath, "utf8"));
     const gitRemoteUrl = (0, utils_1.getGitRemoteUrl)(process.cwd()) ?? undefined;
     return shared.apiRequest("POST", "/api/cli/push", {
@@ -155,10 +150,6 @@ async function runPush(args) {
         console.error(`File is empty: ${absolute}`);
         process.exit(1);
     }
-    // Stored key defaults to the basename (legacy behavior). `--as` overrides it
-    // so callers can namespace generically-named files — e.g. Spec Kit emits a
-    // `plan.md`/`spec.md` per feature, which would otherwise all collide on one
-    // key and silently version over each other.
     const filename = as ?? path.basename(absolute);
     const start = Date.now();
     try {
@@ -179,9 +170,6 @@ async function runPush(args) {
         const tagSummary = res.tags && res.tags.length > 0 ? ` tags=[${res.tags.join(", ")}]` : "";
         console.log(`✓ Pushed ${filename} (kind=${res.kind}${tagSummary}).`);
         console.log(`  Visible under: ${res.destination}`);
-        // Echo the *resolved* key the server stored, not the local filename —
-        // skills are keyed by their frontmatter name (so two `SKILL.md` files
-        // don't collide), so the stored key can differ from what was pushed.
         if (res.key && res.key !== filename) {
             console.log(`  Stored as: ${res.key}`);
         }

package/dist/commands/search.js

@@ -1,8 +1,4 @@
 "use strict";
-// `codiedev search "<query>"` — semantic + keyword search across the org's
-// captured sessions, artifacts, and skills. Hits are filtered by companyId
-// server-side, so a single search surfaces results from every teammate's
-// prior sessions in the same workspace.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runSearch = runSearch;
 const shared_1 = require("./shared");