@instafy/cli 0.2.3 → 0.3.0

package/dist/bind/src/check.mjs

@@ -0,0 +1,176 @@
+// `instafy-bind check <dir> --expect "<item>,<item>"`: does the site show every item the request named?
+// A builder that loses an item to a lookup that timed out, or trims a list to what fits, must not ship a page that
+// quietly leaves it out. The check reads what the page can show without a browser: the text of its HTML pages and
+// every string in its data files (data.json, data/**/*.json, records included). Items come from --expect and from
+// an "expect" array in data.json. Text that only says an item is unavailable ("Not found yet: Tokyo", a data file's
+// "missing" list) does not count as showing it: builders are told to say on the page what they could not add, and
+// that line must not pass the check. Pure helpers are exported for the tests.
+// SPDX-License-Identifier: AGPL-3.0-only
+import fs from "node:fs";
+import path from "node:path";
+
+const SKIP_DIRS = new Set([".bind", "node_modules", "handlers", ".git", ".uwcache", "test", "tests"]);
+const MAX_FILE_BYTES = 4 * 1024 * 1024;
+const MAX_FILES = 400;
+const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
+
+/** "Brooks Adrenaline GTS 24, Hoka Arahi 7" (commas, semicolons or new lines), a JSON array of names, or an array of
+ *  names / { name } objects → unique names in order. */
+export function parseExpect(raw) {
+  let list = raw;
+  if (raw == null || raw === "") return [];
+  if (typeof raw === "string") {
+    if (/^\s*\[/.test(raw)) {
+      try {
+        list = JSON.parse(raw);
+      } catch (error) {
+        throw new Error(`--expect is not a JSON array (${error.message})`);
+      }
+    } else list = raw.split(/[,;\n]/);
+  }
+  if (!Array.isArray(list)) return [];
+  const out = [];
+  for (const entry of list) {
+    const name = String(entry && typeof entry === "object" ? entry.name ?? "" : entry ?? "").trim();
+    if (name && !out.some((x) => norm(x) === norm(name))) out.push(name);
+  }
+  return out;
+}
+
+const norm = (text) => String(text ?? "").normalize("NFKC").toLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+
+/** Does the text name the item, as whole words ("Gel-Kayano 31" in "ASICS Gel Kayano 31 review"; not "Arahi 7" in
+ *  "Arahi 75")? Scripts written without spaces (日本語, 中文) match as a substring. */
+export function names(text, item) {
+  const want = norm(item);
+  if (!want) return false;
+  const hay = ` ${norm(text)} `;
+  return CJK.test(want) ? hay.includes(want) : hay.includes(` ${want} `);
+}
+
+/** The visible text of an HTML page: no scripts, styles, comments or tags. */
+export function htmlText(html) {
+  return String(html ?? "")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/<(script|style|template)\b[\s\S]*?<\/\1\s*>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/gi, "&")
+    .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
+    .replace(/\s+/g, " ");
+}
+
+/** A line or string that only says an item is unavailable (the eval grader reads pages the same way). */
+export const UNAVAILABLE_RE = /^\s*(not found( yet)?|missing|not on the (map|page)( yet)?|could ?n[o']t (find|add|place)|unavailable|not available)\b/i;
+/** Data keys that list what the page could not show ("missing": [...] in the map pack's data). */
+const UNAVAILABLE_KEYS = new Set(["expect", "missing", "notfound", "not_found", "unavailable", "unplaced"]);
+
+/** The visible text of an HTML page as lines (block ends and <br> break them), without lines that only say an item is
+ *  unavailable. */
+export function htmlLines(html) {
+  const blocks = String(html ?? "")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/<(script|style|template)\b[\s\S]*?<\/\1\s*>/gi, " ")
+    .replace(/<br\s*\/?>|<\/(p|div|li|dt|dd|tr|td|th|h[1-6]|section|article|header|footer|aside|nav|figcaption|caption|summary|details|blockquote|pre|ul|ol|dl|table|main)\s*>/gi, "\n");
+  return htmlText(blocks.replace(/\n/g, " \u0000 "))
+    .split("\u0000")
+    .map((line) => line.trim())
+    .filter((line) => line && !UNAVAILABLE_RE.test(line));
+}
+
+/** Every string value in a JSON value (keys are not shown, values are), except the "expect" list, lists of what is
+ *  unavailable, and strings that only say an item is. */
+export function jsonStrings(value, out = []) {
+  if (typeof value === "string") {
+    if (!UNAVAILABLE_RE.test(value)) out.push(value);
+  } else if (typeof value === "number") out.push(String(value));
+  else if (Array.isArray(value)) for (const v of value) jsonStrings(v, out);
+  else if (value && typeof value === "object") {
+    for (const [k, v] of Object.entries(value)) if (!UNAVAILABLE_KEYS.has(k.toLowerCase())) jsonStrings(v, out);
+  }
+  return out;
+}
+
+function siteFiles(root) {
+  const files = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (files.length >= MAX_FILES) return;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".") && depth < 4) walk(full, depth + 1);
+      } else if (entry.isFile() && /\.(html?|json)$/i.test(entry.name) && entry.name !== "bound.json" && entry.name !== "package.json") {
+        files.push(full);
+      }
+    }
+  };
+  walk(root, 0);
+  return files;
+}
+
+/** What the site can show: [{ file, text }] for its HTML pages and data files, and the "expect" list of data.json. */
+export function readSite(dir) {
+  const root = path.resolve(dir);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error(`no site folder at ${dir}`);
+  const parts = [];
+  let declared = [];
+  for (const file of siteFiles(root)) {
+    let raw;
+    try {
+      if (fs.statSync(file).size > MAX_FILE_BYTES) continue;
+      raw = fs.readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    const rel = path.relative(root, file).split(path.sep).join("/");
+    if (/\.json$/i.test(file)) {
+      let value;
+      try {
+        value = JSON.parse(raw);
+      } catch {
+        continue;
+      }
+      if (rel === "data.json" && Array.isArray(value?.expect)) declared = parseExpect(value.expect);
+      parts.push({ file: rel, text: jsonStrings(value).join("\n") });
+    } else parts.push({ file: rel, text: htmlLines(raw).join("\n") });
+  }
+  return { root, parts, declared };
+}
+
+/** Which expected items the site shows, and where; which it leaves out. */
+export function checkSite(dir, expect = []) {
+  const site = readSite(dir);
+  const items = parseExpect([...site.declared, ...parseExpect(expect)]);
+  const shown = [];
+  const missing = [];
+  for (const item of items) {
+    const where = site.parts.filter((p) => names(p.text, item)).map((p) => p.file);
+    if (where.length) shown.push({ item, files: where.slice(0, 3) });
+    else missing.push(item);
+  }
+  return { items, shown, missing, files: site.parts.map((p) => p.file) };
+}
+
+/** The CLI's lines and exit code: 0 every item shown, 1 some missing, 2 nothing to check. */
+export function checkReport(dir, expect, { json = false } = {}) {
+  const result = checkSite(dir, expect);
+  if (!result.items.length) {
+    const message = 'nothing to check: pass --expect "<item>,<item>" (each item the request named) or put "expect": [...] in data.json';
+    return { exit: 2, lines: [json ? JSON.stringify({ ok: false, error: message }) : message] };
+  }
+  if (json) return { exit: result.missing.length ? 1 : 0, lines: [JSON.stringify({ ok: !result.missing.length, ...result })] };
+  const lines = [];
+  if (result.missing.length) {
+    lines.push(`MISSING: the request named ${result.missing.length} item(s) the site does not show: ${result.missing.join(", ")}.`);
+    lines.push("Add each one to the page (its data file), or say plainly in the reply which are missing and why.");
+  }
+  lines.push(`${result.shown.length} of ${result.items.length} expected item(s) shown${result.shown.length ? `: ${result.shown.map((s) => s.item).join(", ")}` : ""}.`);
+  lines.push(`Read ${result.files.length} file(s): the HTML text and the data files (what a script renders from elsewhere is not seen).`);
+  return { exit: result.missing.length ? 1 : 0, lines };
+}

package/dist/bind/src/config.mjs

@@ -0,0 +1,169 @@
+// Controller URL, access token, conversation and space, resolved like the Instafy CLI (`instafy chat`).
+// The token is kept on a non-enumerable property so logging or serialising the config never prints it.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { credentialFreeEnv } from "./detached-env.mjs";
+
+export const DEFAULT_CONTROLLER_URL = "http://127.0.0.1:8788";
+
+const clean = (value) => {
+  const trimmed = typeof value === "string" ? value.trim() : "";
+  if (!trimmed || ["null", "undefined"].includes(trimmed.toLowerCase())) return null;
+  return trimmed;
+};
+const normalizeUrl = (value) => clean(value)?.replace(/\/$/, "") ?? null;
+
+function originOf(raw, label) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`${label} must be a valid URL`);
+  }
+  if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password) {
+    throw new Error(`${label} must use http(s) and must not contain credentials`);
+  }
+  return url.origin;
+}
+
+function readJson(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Nearest .instafy/space.json from cwd upwards (the CLI's project manifest). */
+export function findSpaceManifest(cwd) {
+  let current = path.resolve(cwd);
+  for (;;) {
+    const file = path.join(current, ".instafy", "space.json");
+    if (fs.existsSync(file)) {
+      const parsed = readJson(file);
+      const spaceId = clean(parsed.spaceId) ?? clean(parsed.space_id);
+      if (spaceId) return { ...parsed, spaceId, file };
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/**
+ * Resolve the controller connection.
+ * Order (like the CLI, except for the runtime job credential):
+ * - URL: --server-url, the runtime job binding (CONTROLLER_BASE_URL), INSTAFY_SERVER_URL, the CLI config, the default.
+ * - Token: --access-token, INSTAFY_ACCESS_TOKEN, SUPABASE_ACCESS_TOKEN, then the CLI config's token when its saved
+ *   origin matches. The runtime job credential (CONTROLLER_ACCESS_TOKEN) is never used: it stops working when the
+ *   Octo turn that started `serve` ends, so a long-lived binder must not depend on it.
+ * - The owner's conversation (parent of the site's thread): --conversation, INSTAFY_CONVERSATION_ID, CONVERSATION_ID.
+ * - The agent conversation: --agent-conversation, INSTAFY_BIND_CONVERSATION_ID. Without it the binder creates the
+ *   site's own thread in the space on the first agent intent.
+ * - Space: --space, SPACE_ID, INSTAFY_SPACE_ID, PROJECT_ID, INSTAFY_PROJECT_ID, .instafy/space.json.
+ */
+export function resolveControllerConfig({
+  serverUrl = null,
+  accessToken = null,
+  conversation = null,
+  agentConversation = null,
+  space = null,
+  env = process.env,
+  cwd = process.cwd(),
+  home = os.homedir(),
+} = {}) {
+  const manifest = findSpaceManifest(cwd);
+  const profile = clean(env.INSTAFY_PROFILE) ?? clean(manifest?.profile);
+  if (profile && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(profile)) throw new Error(`invalid Instafy profile "${profile}"`);
+  const configFile = profile ? path.join(home, ".instafy", "profiles", `${profile}.json`) : path.join(home, ".instafy", "config.json");
+  const stored = readJson(configFile);
+  const conversationId = clean(conversation) ?? clean(env.INSTAFY_CONVERSATION_ID) ?? clean(env.CONVERSATION_ID);
+
+  let runtime = null;
+  // The runtime's job binding. Its token is never used (see above), so a binder started with --detach does not even
+  // receive it (detachedBinderEnv); the binding is still recognised to say why agent intents are unavailable.
+  if (clean(env.RUNTIME_ID) && conversationId && clean(env.CONTROLLER_BASE_URL)) {
+    runtime = { controllerUrl: normalizeUrl(env.CONTROLLER_BASE_URL) };
+    originOf(runtime.controllerUrl, "CONTROLLER_BASE_URL");
+  }
+
+  const controllerUrl =
+    normalizeUrl(serverUrl) ?? runtime?.controllerUrl ?? normalizeUrl(env.INSTAFY_SERVER_URL) ?? normalizeUrl(stored.controllerUrl) ?? DEFAULT_CONTROLLER_URL;
+  const origin = originOf(controllerUrl, "controller URL");
+
+  let token = null;
+  let tokenSource = "none";
+  let note = null;
+  if (clean(accessToken)) {
+    token = clean(accessToken);
+    tokenSource = "explicit";
+  } else if (clean(env.INSTAFY_ACCESS_TOKEN)) {
+    token = clean(env.INSTAFY_ACCESS_TOKEN);
+    tokenSource = "env:INSTAFY_ACCESS_TOKEN";
+  } else if (clean(env.SUPABASE_ACCESS_TOKEN)) {
+    token = clean(env.SUPABASE_ACCESS_TOKEN);
+    tokenSource = "env:SUPABASE_ACCESS_TOKEN";
+  } else if (clean(stored.accessToken)) {
+    const savedOrigin = normalizeUrl(stored.controllerUrl) ? originOf(normalizeUrl(stored.controllerUrl), "saved controller URL") : null;
+    if (savedOrigin === origin) {
+      token = clean(stored.accessToken);
+      tokenSource = "config";
+    } else {
+      note = "the saved login belongs to a different controller; it is not used";
+    }
+  }
+
+  if (!token && runtime) {
+    tokenSource = "runtime-refused";
+    note = "only the runtime job token is available; it stops working when this Octo turn ends, so agent intents need `instafy login` or INSTAFY_ACCESS_TOKEN";
+  }
+
+  const spaceId =
+    clean(space) ?? clean(env.SPACE_ID) ?? clean(env.INSTAFY_SPACE_ID) ?? clean(env.PROJECT_ID) ?? clean(env.INSTAFY_PROJECT_ID) ?? manifest?.spaceId ?? null;
+  const agentConversationId = clean(agentConversation) ?? clean(env.INSTAFY_BIND_CONVERSATION_ID);
+
+  const config = { controllerUrl, tokenSource, hasToken: Boolean(token), conversationId, agentConversationId, spaceId, profile, configFile, note };
+  Object.defineProperty(config, "token", { value: token, enumerable: false });
+  return config;
+}
+
+/** Why the agent executor cannot dispatch, or null when it can. */
+export function agentUnavailableReason(config) {
+  if (config.tokenSource === "runtime-refused") return "the runtime job token ends with this Octo turn; run `instafy login` or set INSTAFY_ACCESS_TOKEN";
+  if (!config.hasToken) return "no Instafy access token (run `instafy login`, or set INSTAFY_ACCESS_TOKEN)";
+  if (!config.agentConversationId && !config.spaceId) {
+    return "no space for the site's own Octo thread (pass --space, or --agent-conversation <id> to use an existing conversation)";
+  }
+  return null;
+}
+
+/** True when agent turns would go into the owner's own working conversation. */
+export function agentUsesOwnerConversation(config) {
+  return Boolean(config.agentConversationId && config.conversationId && config.agentConversationId === config.conversationId);
+}
+
+/** Credential names the binder itself reads as the owner's login (above). */
+const BINDER_LOGIN_ENV = ["INSTAFY_ACCESS_TOKEN", "SUPABASE_ACCESS_TOKEN"];
+
+/**
+ * Why --agent-executor is refused here, or null. It treats a click from this machine's loopback as the owner's own,
+ * which is only true on a single-user machine. An Instafy runtime (a job binding: RUNTIME_ID or CONTROLLER_BASE_URL)
+ * is shared: other members' Octo turns run there and could click on the owner's login, so it fails closed.
+ */
+export function agentExecutorRefusal(env = process.env) {
+  if (!clean(env.RUNTIME_ID) && !clean(env.CONTROLLER_BASE_URL)) return null;
+  return "--agent-executor runs Octo turns on your own login for clicks from this machine, so it needs a machine only you use; this is a shared Instafy runtime (RUNTIME_ID or CONTROLLER_BASE_URL is set). Ask Octo works without it: clicks in Studio are sent as the clicker's own message";
+}
+
+/**
+ * The environment of a binder started with `serve --detach`: `credentialFreeEnv` (no runtime job token or other
+ * CONTROLLER_* secret, no SUPABASE_* service values, no credential-like names such as space secrets), except names
+ * passed with --allow-env, and the owner's login only with `keepLogin` (--agent-executor, the one mode that
+ * dispatches Octo turns itself). Everything else (PATH, HOME, the space and conversation ids, plain settings a
+ * handler may declare in `env`) is kept.
+ */
+export function detachedBinderEnv(env = process.env, allowEnv = [], { keepLogin = false } = {}) {
+  return credentialFreeEnv(env, [...allowEnv, ...(keepLogin ? BINDER_LOGIN_ENV : [])]);
+}

package/dist/bind/src/controller.mjs

@@ -0,0 +1,244 @@
+// Minimal controller API client: the calls `instafy chat --wait --json` makes (packages/instafy-cli/src/chat.ts),
+// reimplemented without dependencies, plus creating the site's own thread and cancelling a job.
+// Shapes follow packages/runtime-controller: messages come back newest first with createdAt; a finished run's
+// status is "success" (or failed, canceled, merged, expired); dispatch answers {status, runId?, jobId?, conversationId}.
+
+const TERMINAL = ["success", "succeeded", "completed", "complete", "merged", "ready", "failed", "error", "errored", "cancelled", "canceled", "expired"];
+const SUCCESS = ["success", "succeeded", "completed", "complete", "merged", "ready"];
+const NON_REPLY_TYPES = [
+  "token_usage", "command_execution", "mcp_tool_call", "plan_update", "learn_router",
+  "integration_request", "status", "activity", "thread_update",
+];
+
+const lower = (status) => String(status ?? "").trim().toLowerCase();
+export const isTerminalStatus = (status) => TERMINAL.includes(lower(status));
+export const isSuccessfulStatus = (status) => SUCCESS.includes(lower(status));
+export const isWaitingForApproval = (status) => lower(status) === "awaiting_approval";
+
+export function messageRunId(message) {
+  const raw = message?.runId ?? message?.run_id ?? null;
+  return typeof raw === "string" && raw.trim() ? raw.trim() : null;
+}
+
+export function messageType(message) {
+  const metadata = message?.metadata;
+  if (!metadata || typeof metadata !== "object") return null;
+  const direct = metadata.messageType ?? metadata.message_type;
+  return typeof direct === "string" && direct.trim() ? direct.trim().toLowerCase() : null;
+}
+
+/** Raw `{...}` or a single ```json fenced object. */
+export function looksLikeJsonObjectReply(content) {
+  const trimmed = String(content ?? "").trim();
+  if (!trimmed) return false;
+  if (trimmed.startsWith("{") && trimmed.endsWith("}")) return true;
+  const fence = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  if (fence) {
+    const inner = fence[1].trim();
+    return inner.startsWith("{") && inner.endsWith("}");
+  }
+  return false;
+}
+
+/** An assistant message that can be the run's reply (status messages only when they hold a JSON object). */
+export function isReplyCandidate(message, runId) {
+  if (String(message?.role ?? "").toLowerCase() !== "assistant") return false;
+  if (runId && messageRunId(message) !== runId) return false;
+  if (typeof message.content !== "string" || !message.content.trim()) return false;
+  const type = messageType(message);
+  if (type === "status") return looksLikeJsonObjectReply(message.content);
+  return !(type && NON_REPLY_TYPES.includes(type));
+}
+
+const createdAt = (message) => Date.parse(message?.createdAt ?? message?.created_at ?? "");
+
+/** Messages sorted newest first by createdAt. Messages without a time keep the server's order after timed ones. */
+export function newestFirst(messages) {
+  return messages
+    .map((message, index) => ({ message, index, at: createdAt(message) }))
+    .sort((a, b) => {
+      const at = Number.isFinite(a.at), bt = Number.isFinite(b.at);
+      if (at && bt && a.at !== b.at) return b.at - a.at;
+      if (at !== bt) return at ? -1 : 1;
+      return a.index - b.index;
+    })
+    .map((entry) => entry.message);
+}
+
+/**
+ * The run's reply: among its reply candidates, newest first, the first one `accept` takes (by default a bare
+ * JSON object), else the newest candidate. Skips ids in `exclude`.
+ */
+export function findLatestReply(messages, runId, { exclude = new Set(), accept = (m) => looksLikeJsonObjectReply(m.content) } = {}) {
+  let newest = null;
+  for (const message of newestFirst(messages)) {
+    if (!message || exclude.has(message.id) || !isReplyCandidate(message, runId)) continue;
+    if (accept(message)) return message;
+    newest ??= message;
+  }
+  return newest;
+}
+
+export class ControllerError extends Error {
+  constructor(message, { status = 0, code = "upstream", viewerMessage = "Octo is unavailable right now" } = {}) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    /** What viewers see; the detail above stays in the binder log. */
+    this.viewerMessage = viewerMessage;
+  }
+}
+
+/** One signal that aborts when either does (AbortSignal.any is Node 20+). */
+function anySignal(signals) {
+  const controller = new AbortController();
+  for (const signal of signals.filter(Boolean)) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      break;
+    }
+    signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+  }
+  return controller.signal;
+}
+
+/** metadata.purpose of the conversation a binder creates for a site's Octo turns. */
+export const BIND_THREAD_PURPOSE = "bound-site-agent-thread";
+
+export class ControllerClient {
+  /**
+   * @param {{controllerUrl: string, token: string, refreshToken?: () => Promise<string|null>|string|null, fetchImpl?: typeof fetch, timeoutMs?: number}} options
+   * refreshToken is asked once after a 401 (the CLI may have refreshed its saved login meanwhile).
+   */
+  constructor({ controllerUrl, token, refreshToken = null, fetchImpl = globalThis.fetch, timeoutMs = 60_000 }) {
+    this.base = new URL(`${controllerUrl.replace(/\/$/, "")}/`);
+    Object.defineProperty(this, "token", { value: token, enumerable: false, writable: true });
+    this.refreshToken = refreshToken;
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async request(method, path, { query = {}, body, signal = null, timeoutMs = this.timeoutMs, retried = false } = {}) {
+    const url = new URL(path.replace(/^\//, ""), this.base);
+    if (url.origin !== this.base.origin) throw new ControllerError("refusing a cross-origin controller request", { code: "policy" });
+    for (const [key, value] of Object.entries(query)) url.searchParams.set(key, String(value));
+    const headers = { accept: "application/json" };
+    if (this.token) headers.authorization = `Bearer ${this.token}`;
+    if (body !== undefined) headers["content-type"] = "application/json";
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        redirect: "error",
+        signal: anySignal([AbortSignal.timeout(timeoutMs), signal]),
+      });
+    } catch (error) {
+      if (signal?.aborted) throw signal.reason;
+      throw new ControllerError(`controller unreachable: ${error.message}`);
+    }
+    const text = await response.text().catch(() => "");
+    if (response.status === 401 && !retried && this.refreshToken) {
+      const fresh = await Promise.resolve(this.refreshToken()).catch(() => null);
+      if (fresh && fresh !== this.token) {
+        this.token = fresh;
+        return this.request(method, path, { query, body, signal, timeoutMs, retried: true });
+      }
+    }
+    if (response.status === 401 || response.status === 403) {
+      throw new ControllerError(`controller rejected the access token (${response.status}); run \`instafy login\``, {
+        status: response.status,
+        code: "policy",
+        viewerMessage: "Octo is not available: the site owner's Instafy login was rejected",
+      });
+    }
+    if (!response.ok) {
+      throw new ControllerError(`controller ${method} ${url.pathname} failed (${response.status}): ${text.slice(0, 200)}`, { status: response.status });
+    }
+    try {
+      return text ? JSON.parse(text) : null;
+    } catch {
+      throw new ControllerError(`controller ${method} ${url.pathname} returned non-JSON`);
+    }
+  }
+
+  /** POST a prompt to a conversation. Returns {conversationId, runId, jobId, promptId, status}. */
+  async dispatch({ prompt, conversationId, intent = "feature", metadata = {}, signal = null }) {
+    if (!conversationId) throw new ControllerError("no conversation to dispatch to", { code: "policy" });
+    const payload = { promptText: prompt, intent, metadata };
+    const response = await this.request("POST", `/conversations/${encodeURIComponent(conversationId)}/messages`, { body: payload, signal });
+    const pick = (value) => (typeof value === "string" && value.trim() ? value.trim() : null);
+    return {
+      conversationId: pick(response?.conversationId) || conversationId,
+      runId: pick(response?.runId),
+      jobId: pick(response?.jobId),
+      promptId: pick(response?.promptId),
+      status: pick(response?.status),
+    };
+  }
+
+  /**
+   * Create the conversation the site's agent turns go to. The controller (runtime-controller conversations.rs,
+   * resolve_thread_columns) accepts `threadKind` only together with `parentConversationId`, so:
+   * - with a parent: a private child thread `{parentConversationId, threadKind: "bind"}` under the owner's conversation;
+   * - without one: a root conversation in the space (no threadKind), marked as the binder's own work thread.
+   * When the parent is refused (400/403/404: gone, another space, private, internal), it falls back to a root
+   * conversation and reports why through `onFallback`. Returns {conversationId, parentConversationId}.
+   *
+   * The controller has no client-settable "hidden" or "internal" conversation (conversations.internal_purpose is
+   * set by controller code only, and strip_client_internal_metadata drops a client's internalPurpose), so the root
+   * conversation is made as hidden as the API allows: `visibility: "private"` keeps it out of every other member's
+   * conversation list, and `metadata.source` / `metadata.purpose` mark it as a tool's thread so Studio never binds
+   * it to a user's chat tab (frontend conversationAdoption.ts keys on `source`).
+   */
+  async createThreadRecord({ spaceId, parentConversationId = null, title = null, signal = null, onFallback = null }) {
+    if (!spaceId) throw new ControllerError("no space to create the site's thread in", { code: "policy" });
+    const metadata = {
+      source: "instafy-bind",
+      purpose: BIND_THREAD_PURPOSE,
+      ...(title ? { title: `Bound site: ${title}`.slice(0, 120) } : {}),
+    };
+    // Private in both cases: a viewer's click (their search, a rounded position, private_params) is posted here,
+    // and only the owner who serves the site should read it, not every member who can see the parent.
+    const create = async (parent) => {
+      const body = parent
+        ? { metadata: { ...metadata, visibility: "private" }, parentConversationId: parent, threadKind: "bind" }
+        : { metadata: { ...metadata, visibility: "private" } };
+      const response = await this.request("POST", `/projects/${encodeURIComponent(spaceId)}/conversations/blank`, { body, signal });
+      const id = typeof response?.conversationId === "string" ? response.conversationId.trim() : "";
+      if (!id) throw new ControllerError("conversation creation response missing conversationId");
+      return { conversationId: id, parentConversationId: parent };
+    };
+    const parent = typeof parentConversationId === "string" && parentConversationId.trim() ? parentConversationId.trim() : null;
+    if (!parent) return create(null);
+    try {
+      return await create(parent);
+    } catch (error) {
+      if (!(error instanceof ControllerError) || ![400, 403, 404].includes(error.status)) throw error;
+      onFallback?.(error);
+      return create(null);
+    }
+  }
+
+  /** {@link createThreadRecord}, returning only the new conversation id. */
+  async createThread(options) {
+    return (await this.createThreadRecord(options)).conversationId;
+  }
+
+  /** Ask the controller to stop a dispatched job (best effort). */
+  async cancelJob(jobId, reason = "Cancelled from the bound site") {
+    return this.request("POST", `/jobs/${encodeURIComponent(jobId)}/cancel`, { body: { reason }, timeoutMs: 10_000 });
+  }
+
+  async run(conversationId, runId, { signal = null } = {}) {
+    const runs = await this.request("GET", `/conversations/${encodeURIComponent(conversationId)}/runs`, { query: { limit: 20 }, signal });
+    return Array.isArray(runs) ? runs.find((run) => run?.id === runId) ?? null : null;
+  }
+
+  /** The newest messages of a conversation, newest first. */
+  async messages(conversationId, { limit = 50, signal = null } = {}) {
+    const page = await this.request("GET", `/conversations/${encodeURIComponent(conversationId)}/messages`, { query: { limit }, signal });
+    return newestFirst(Array.isArray(page?.messages) ? page.messages : []);
+  }
+}

package/dist/bind/src/detached-env.mjs

@@ -0,0 +1,27 @@
+// The environment of a process started to outlive the command (or Octo turn) that started it.
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// Shared by `instafy bind serve --detach` and `instafy preview open --start` (the CLI loads this file from its bundled
+// copy of the binder), so both strip the same credentials.
+
+const CREDENTIAL_ENV_RE = /(TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|PRIVATE|(^|_)KEY$|_KEY_|API_?KEY)/;
+
+/**
+ * `env` without credentials a long-lived process does not need. Such a process outlives the job that started it, and
+ * every process in a runtime can read its /proc/<pid>/environ, so it keeps no runtime job token or other CONTROLLER_*
+ * value (except CONTROLLER_BASE_URL, which is not secret), no SUPABASE_* value and no credential-like name (space
+ * secrets, logins). Names in `keep` are kept anyway. Everything else (PATH, HOME, the space and conversation ids,
+ * plain settings) is kept.
+ */
+export function credentialFreeEnv(env = process.env, keep = []) {
+  const out = {};
+  for (const [name, value] of Object.entries(env)) {
+    if (value === undefined) continue;
+    const kept =
+      keep.includes(name) ||
+      name === "CONTROLLER_BASE_URL" ||
+      (!/^(CONTROLLER|SUPABASE)_/.test(name) && !CREDENTIAL_ENV_RE.test(name));
+    if (kept) out[name] = value;
+  }
+  return out;
+}