@flowriki/agent 0.1.0-beta.36 → 0.1.0-beta.39

package/dist/{chunk-N3P4O3OH.js → chunk-7CH5XDEE.js}

@@ -6,7 +6,7 @@ import os from "os";
 import path from "path";
 import { createRequire } from "module";
 import { spawnSync } from "child_process";
-var AGENT_VERSION = "0.1.0-beta.36";
+var AGENT_VERSION = "0.1.0-beta.39";
 async function prepareBrowsers() {
   if (browsersReady()) {
     return { ok: true, already: true, message: "chromium is already installed" };
@@ -113,29 +113,29 @@ function allConnections(env = process.env) {
 }
 function saveConnection(connection, env = process.env) {
   ensureDataDir(env);
-  const file = credentialsPath(env);
+  const file2 = credentialsPath(env);
   const next = {
     version: 3,
     connections: [...readFile(env).connections.filter((c) => c.service !== connection.service), connection]
   };
-  const temporary = `${file}.${process.pid}.tmp`;
+  const temporary = `${file2}.${process.pid}.tmp`;
   fs3.writeFileSync(temporary, JSON.stringify(next, null, 2) + "\n", { mode: 384 });
-  fs3.renameSync(temporary, file);
+  fs3.renameSync(temporary, file2);
 }
 function forgetConnection(service, env = process.env) {
   const before = readFile(env).connections;
   const after = before.filter((c) => c.service !== service);
   if (after.length === before.length) return false;
   ensureDataDir(env);
-  const file = credentialsPath(env);
-  const temporary = `${file}.${process.pid}.tmp`;
+  const file2 = credentialsPath(env);
+  const temporary = `${file2}.${process.pid}.tmp`;
   fs3.writeFileSync(temporary, JSON.stringify({ version: 3, connections: after }, null, 2) + "\n", { mode: 384 });
-  fs3.renameSync(temporary, file);
+  fs3.renameSync(temporary, file2);
   return true;
 }
 var fingerprint = (secret2) => crypto2.createHash("sha256").update(secret2).digest("hex").slice(0, 12);
 
-// ../contracts/dist/chunk-UFMRFPRU.js
+// ../contracts/dist/chunk-4VVBTBPF.js
 import { z } from "zod";
 var PROTOCOL_VERSION = 1;
 var PAIRING_CODE_TTL_MS = 5 * 60 * 1e3;
@@ -168,7 +168,15 @@ var CommandNameSchema = z.enum([
   "runs.list",
   "runs.stats",
   "run.get",
-  "artifact.fetch"
+  "artifact.fetch",
+  // The AI assistant on this machine, driven from the dashboard. NOT baseline: an
+  // agent from before these existed must be told so up front rather than be
+  // sent a command it has no handler for.
+  "assistant.status",
+  "assistant.connect",
+  "assistant.ask",
+  "assistant.cancel",
+  "assistant.folder"
 ]);
 var EFFECTFUL = /* @__PURE__ */ new Set([
   "record.start",
@@ -200,6 +208,13 @@ var EFFECTFUL = /* @__PURE__ */ new Set([
   // dropped socket would find it already there and report a failure for
   // something that had in fact succeeded.
   "feature.create",
+  // Signing in opens a browser on somebody's machine; asking starts a program
+  // that spends their assistant usage and can record tests. Neither is a read,
+  // and a blind retry after a dropped socket would do either twice.
+  // (`assistant.status` stays out: reading is safe to repeat.)
+  "assistant.connect",
+  "assistant.ask",
+  "assistant.cancel",
   // Claiming writes a file, makes a commit and pushes. Blind retry after a
   // dropped socket would commit twice.
   "project.claim",
@@ -990,6 +1005,9 @@ import { z as z4 } from "zod";
 import { z as z22 } from "zod";
 import { z as z32 } from "zod";
 import { z as z42 } from "zod";
+import { z as z5 } from "zod";
+import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var EngineSchema = z4.enum(["chromium", "firefox", "webkit"]);
 var CapabilitySchema = z4.object({
   id: z4.string(),
@@ -1756,6 +1774,285 @@ var DeliveredHelperSchema = z42.object({
   name: z42.string(),
   config: HelperConfigSchema
 }).strict();
+var LIBRARY_CASE_SCHEMA_VERSION = 1;
+var TEST_TYPES = ["functional", "negative", "edge", "regression", "smoke", "accessibility", "other"];
+var PRIORITIES = ["P0", "P1", "P2", "P3"];
+var CASE_STATUSES = ["draft", "ready", "deprecated"];
+var AUTOMATION_STATES = ["none", "planned", "automated", "not-automatable"];
+var LibraryStepSchema = z5.object({
+  id: z5.string().min(1),
+  action: z5.string().min(1),
+  /** What to type or choose, when the action needs it. */
+  data: z5.string().optional(),
+  /** What should happen. Absent for a step that only gets somewhere. */
+  expected: z5.string().optional()
+}).strict();
+var AutomationLinkSchema = z5.object({
+  automationId: z5.string().min(1),
+  caseRevision: z5.number().int().nonnegative(),
+  /** The automation's revision when the link was made or last confirmed —
+   *  an automation edited since may no longer check what the case says. */
+  automationRevision: z5.number().int().nonnegative().optional(),
+  at: z5.string(),
+  by: z5.string().default("")
+}).strict();
+var CaseOriginSchema = z5.discriminatedUnion("kind", [
+  z5.object({ kind: z5.literal("manual") }).strict(),
+  z5.object({
+    kind: z5.literal("import"),
+    /** "csv", "xlsx", "testrail", "zephyr", "xray", "text"… */
+    format: z5.string().min(1),
+    file: z5.string().min(1),
+    /** Row or item in that file, to find it again. */
+    row: z5.string().optional()
+  }).strict(),
+  z5.object({
+    kind: z5.literal("generated"),
+    sourceId: z5.string().min(1),
+    sourceVersion: z5.number().int().positive(),
+    requirementIds: z5.array(z5.string().min(1)).default([])
+  }).strict()
+]);
+var TestDataSchema = z5.object({
+  name: z5.string().min(1),
+  value: z5.string().optional(),
+  secretRef: z5.string().regex(/^[a-z][a-z0-9_]*$/i).optional()
+}).strict();
+var LibraryCaseSchema = z5.object({
+  schemaVersion: z5.literal(LIBRARY_CASE_SCHEMA_VERSION),
+  id: z5.string().regex(/^tcs_[A-Za-z0-9]+$/),
+  /** "TC-142": what people say out loud. The id is what links point at. */
+  key: z5.string().regex(/^TC-[1-9][0-9]*$/),
+  /** The same features flows are filed under (`f_<slug>`), so one feature
+   *  holds both what to test and what tests it. */
+  featureId: z5.string().min(1),
+  slug: z5.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+  title: z5.string().min(1).max(300),
+  description: z5.string().default(""),
+  type: z5.enum(TEST_TYPES).default("functional"),
+  priority: z5.enum(PRIORITIES).default("P2"),
+  status: z5.enum(CASE_STATUSES).default("draft"),
+  preconditions: z5.array(z5.string().min(1)).default([]),
+  steps: z5.array(LibraryStepSchema).default([]),
+  testData: z5.array(TestDataSchema).default([]),
+  tags: z5.array(z5.string().min(1)).default([]),
+  /** Requirement ids (Flowriki storage). The text is not copied here. */
+  covers: z5.array(z5.string().min(1)).default([]),
+  automation: z5.object({
+    state: z5.enum(AUTOMATION_STATES).default("none"),
+    /** Why it cannot be automated, when it cannot. */
+    reason: z5.string().optional(),
+    /** The plan for automating it: flows to reuse, flows to record, checks to
+     *  switch on, accounts and helpers it needs, and what cannot be automated.
+     *  Written (usually by the assistant) and approved before anything is
+     *  recorded. */
+    plan: z5.string().max(2e4).optional(),
+    planApproved: z5.boolean().optional(),
+    links: z5.array(AutomationLinkSchema).default([])
+  }).strict().default({}),
+  origin: CaseOriginSchema.default({ kind: "manual" }),
+  createdAt: z5.string(),
+  createdBy: z5.string().default(""),
+  updatedAt: z5.string(),
+  updatedBy: z5.string().default(""),
+  revision: z5.number().int().nonnegative().default(0)
+}).strict().superRefine((doc, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  doc.steps.forEach((step, i) => {
+    if (seen.has(step.id)) ctx.addIssue({ code: "custom", path: ["steps", i, "id"], message: "Step IDs must be unique" });
+    seen.add(step.id);
+  });
+  const linked = /* @__PURE__ */ new Set();
+  doc.automation.links.forEach((link, i) => {
+    if (linked.has(link.automationId)) {
+      ctx.addIssue({ code: "custom", path: ["automation", "links", i], message: "An automation is linked once" });
+    }
+    linked.add(link.automationId);
+  });
+  if (doc.automation.state === "not-automatable" && !doc.automation.reason?.trim()) {
+    ctx.addIssue({ code: "custom", path: ["automation", "reason"], message: "Say why it cannot be automated" });
+  }
+});
+var normaliseText = (text) => text.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+var SOURCE_KINDS = ["upload", "jira", "figma", "confluence", "linear", "github-issue", "notion", "url"];
+var SourceVersionSchema = z5.object({
+  v: z5.number().int().positive(),
+  hash: z5.string().min(1),
+  extractedText: z5.string(),
+  /** Where the original file is kept, for an upload. */
+  originalKey: z5.string().optional(),
+  mediaType: z5.string().optional(),
+  at: z5.string(),
+  by: z5.string().default("")
+}).strict();
+var SourceSchema = z5.object({
+  id: z5.string().regex(/^src_[A-Za-z0-9]+$/),
+  projectId: z5.string().min(1),
+  title: z5.string().min(1).max(300),
+  kind: z5.enum(SOURCE_KINDS),
+  versions: z5.array(SourceVersionSchema).min(1),
+  integrationId: z5.string().optional(),
+  externalId: z5.string().optional(),
+  externalUrl: z5.string().url().optional(),
+  createdAt: z5.string(),
+  createdBy: z5.string().default("")
+}).strict();
+var RequirementSchema = z5.object({
+  id: z5.string().regex(/^req_[A-Za-z0-9]+$/),
+  projectId: z5.string().min(1),
+  sourceId: z5.string().min(1),
+  sourceVersion: z5.number().int().positive(),
+  /** Where in the source: a heading path, a Jira key, a Figma node. */
+  anchor: z5.string().min(1),
+  text: z5.string().min(1),
+  featureId: z5.string().optional(),
+  /** As of the source's latest version: new in it, changed by it, unchanged
+   *  ("active"), or gone from it. */
+  state: z5.enum(["new", "active", "changed", "removed"]).default("new"),
+  history: z5.array(z5.object({
+    sourceVersion: z5.number().int().positive(),
+    text: z5.string(),
+    state: z5.enum(["new", "active", "changed", "removed"])
+  }).strict()).default([])
+}).strict();
+var MANUAL_OUTCOMES = ["untested", "passed", "failed", "blocked", "skipped"];
+var EvidenceSchema = z6.object({
+  id: z6.string().regex(/^ev_[A-Za-z0-9]+$/),
+  /** A file kept in Flowriki's evidence storage, or a link to one elsewhere. */
+  kind: z6.enum(["file", "link"]),
+  name: z6.string().min(1).max(200),
+  mediaType: z6.string().optional(),
+  size: z6.number().int().nonnegative().optional(),
+  url: z6.string().url().optional(),
+  /** The step it shows, when it belongs to one. */
+  stepId: z6.string().optional(),
+  at: z6.string(),
+  by: z6.string().default("")
+}).strict();
+var StepOutcomeSchema = z6.object({
+  stepId: z6.string().min(1),
+  outcome: z6.enum(MANUAL_OUTCOMES),
+  /** What actually happened, when it was not what was expected. */
+  actual: z6.string().max(4e3).optional()
+}).strict();
+var ManualResultSchema = z6.object({
+  outcome: z6.enum(MANUAL_OUTCOMES),
+  steps: z6.array(StepOutcomeSchema).default([]),
+  note: z6.string().max(8e3).default(""),
+  evidence: z6.array(EvidenceSchema).default([]),
+  bugIds: z6.array(z6.string().min(1)).default([]),
+  tester: z6.string().default(""),
+  at: z6.string()
+}).strict();
+var CycleEntrySchema = z6.object({
+  testCaseId: z6.string().min(1),
+  key: z6.string().min(1),
+  title: z6.string().min(1),
+  featureId: z6.string().min(1),
+  priority: z6.enum(PRIORITIES),
+  /** The case revision snapshot, so "the case changed since" is answerable. */
+  caseRevision: z6.number().int().nonnegative(),
+  preconditions: z6.array(z6.string()).default([]),
+  steps: z6.array(z6.object({ id: z6.string(), action: z6.string(), data: z6.string().optional(), expected: z6.string().optional() }).strict()).default([]),
+  assignee: z6.string().optional(),
+  result: ManualResultSchema.nullable().default(null),
+  /** Earlier results for this case in this cycle, newest last — a retest
+   *  keeps what the first attempt found. */
+  history: z6.array(ManualResultSchema).default([])
+}).strict();
+var TestCycleSchema = z6.object({
+  id: z6.string().regex(/^cyc_[A-Za-z0-9]+$/),
+  projectId: z6.string().min(1),
+  name: z6.string().min(1).max(200),
+  description: z6.string().max(4e3).default(""),
+  status: z6.enum(["open", "closed"]).default("open"),
+  /** Which branch the cases were read from; null for the published tests. */
+  changeId: z6.string().nullable().default(null),
+  entries: z6.array(CycleEntrySchema).default([]),
+  createdAt: z6.string(),
+  createdBy: z6.string().default(""),
+  updatedAt: z6.string(),
+  closedAt: z6.string().nullable().default(null)
+}).strict();
+var BUG_STATUSES = ["open", "in-progress", "fixed", "verified", "closed", "wont-fix"];
+var SEVERITIES = ["critical", "major", "minor", "trivial"];
+var BugSchema = z6.object({
+  id: z6.string().regex(/^bug_[A-Za-z0-9]+$/),
+  key: z6.string().regex(/^BUG-[1-9][0-9]*$/),
+  projectId: z6.string().min(1),
+  title: z6.string().min(1).max(300),
+  description: z6.string().max(2e4).default(""),
+  severity: z6.enum(SEVERITIES).default("major"),
+  status: z6.enum(BUG_STATUSES).default("open"),
+  tracker: z6.enum(["flowriki", "jira", "linear", "github"]).default("flowriki"),
+  externalKey: z6.string().optional(),
+  url: z6.string().url().optional(),
+  /** Where it was found: a case, the step in it, the cycle that ran it. */
+  testCaseIds: z6.array(z6.string()).default([]),
+  cycleIds: z6.array(z6.string()).default([]),
+  runIds: z6.array(z6.string()).default([]),
+  automationIds: z6.array(z6.string()).default([]),
+  foundAt: z6.object({ cycleId: z6.string(), testCaseId: z6.string(), stepId: z6.string().optional() }).strict().optional(),
+  createdAt: z6.string(),
+  createdBy: z6.string().default(""),
+  updatedAt: z6.string()
+}).strict();
+var STOP = new Set("a an the and or of to in on for with by is are be as at it this that from user users can should must shall will when then given".split(" "));
+function similarity(a, b2) {
+  const words = (s2) => new Set(normaliseText(s2).split(" ").filter((w) => w.length > 1 && !STOP.has(w)));
+  const x = words(a);
+  const y = words(b2);
+  if (x.size === 0 || y.size === 0) return 0;
+  let shared = 0;
+  for (const w of x) if (y.has(w)) shared += 1;
+  return shared / (x.size + y.size - shared);
+}
+var ConversationSchema = z7.object({
+  id: z7.string().regex(/^conv_[A-Za-z0-9]+$/),
+  projectId: z7.string().min(1),
+  /** Whose: conversations are personal. */
+  userId: z7.string().min(1),
+  title: z7.string().min(1).max(200),
+  mode: z7.enum(["ask", "do"]).default("ask"),
+  /** The assistant's own session, to continue where it left off. */
+  sessionId: z7.string().optional(),
+  /** The conversation as the dashboard draws it. Kept as given: the shape
+   *  belongs to the screen, and the service only stores and returns it. */
+  lines: z7.array(z7.unknown()).max(2e3).default([]),
+  createdAt: z7.string(),
+  updatedAt: z7.string()
+}).strict();
+var INTEGRATION_PLATFORMS = ["jira", "linear", "github", "figma", "confluence"];
+var IntegrationSchema = z7.object({
+  id: z7.string().regex(/^int_[A-Za-z0-9]+$/),
+  projectId: z7.string().min(1),
+  platform: z7.enum(INTEGRATION_PLATFORMS),
+  name: z7.string().min(1).max(120),
+  /** Where it is: a Jira or Confluence site, a GitHub repository, a Figma
+   *  file, a Linear team. Never a credential. */
+  config: z7.object({
+    baseUrl: z7.string().url().optional(),
+    email: z7.string().optional(),
+    jql: z7.string().max(2e3).optional(),
+    projectKey: z7.string().max(40).optional(),
+    repository: z7.string().regex(/^[\w.-]+\/[\w.-]+$/).optional(),
+    fileKey: z7.string().max(120).optional(),
+    teamKey: z7.string().max(40).optional(),
+    spaceKey: z7.string().max(80).optional(),
+    pageIds: z7.array(z7.string().max(40)).max(200).optional(),
+    /** Raise bugs here when asked. */
+    bugs: z7.boolean().optional(),
+    /** Read items here as sources. */
+    sources: z7.boolean().optional()
+  }).strict(),
+  /** The vault reference for its token. */
+  tokenRef: z7.string().regex(/^[a-z][a-z0-9_]*$/),
+  status: z7.enum(["connected", "failing"]).default("connected"),
+  lastSyncAt: z7.string().nullable().default(null),
+  lastError: z7.string().nullable().default(null),
+  createdAt: z7.string(),
+  createdBy: z7.string().default("")
+}).strict();
 
 // ../engine-playwright/dist/index.js
 import { createHmac, randomBytes as randomBytes2 } from "crypto";
@@ -3990,10 +4287,10 @@ async function captureFailure(opts) {
   }
   let screenshot = null;
   try {
-    const file = `step-${String(ordinal).padStart(2, "0")}.png`;
+    const file2 = `step-${String(ordinal).padStart(2, "0")}.png`;
     fs4.mkdirSync(dir, { recursive: true });
     await page.screenshot({
-      path: path22.join(dir, file),
+      path: path22.join(dir, file2),
       // The viewport, not the full page: a failure is about what was on screen,
       // and a full-page capture of an infinite-scroll app is a 20MB image.
       fullPage: false,
@@ -4004,7 +4301,7 @@ async function captureFailure(opts) {
       maskColor: "#475569",
       timeout: 5e3
     });
-    screenshot = file;
+    screenshot = file2;
   } catch {
     screenshot = null;
   }
@@ -4042,20 +4339,20 @@ async function finaliseArtifacts(opts) {
   const { context, dir, passed, artifacts, consoleLines } = opts;
   const keep = (mode) => mode === "always" || mode === "on-failure" && !passed;
   const out = [];
-  const size = (file) => {
+  const size = (file2) => {
     try {
-      return fs4.statSync(path22.join(dir, file)).size;
+      return fs4.statSync(path22.join(dir, file2)).size;
     } catch {
       return null;
     }
   };
   if (artifacts.trace !== "off") {
-    const file = "trace.zip";
+    const file2 = "trace.zip";
     try {
       if (keep(artifacts.trace)) {
         fs4.mkdirSync(dir, { recursive: true });
-        await context.tracing.stop({ path: path22.join(dir, file) });
-        out.push({ kind: "trace", relPath: file, bytes: size(file) });
+        await context.tracing.stop({ path: path22.join(dir, file2) });
+        out.push({ kind: "trace", relPath: file2, bytes: size(file2) });
       } else {
         await context.tracing.stop();
       }
@@ -4063,11 +4360,11 @@ async function finaliseArtifacts(opts) {
     }
   }
   if (artifacts.console && consoleLines.length) {
-    const file = "console.log";
+    const file2 = "console.log";
     try {
       fs4.mkdirSync(dir, { recursive: true });
-      fs4.writeFileSync(path22.join(dir, file), consoleLines.join("\n") + "\n");
-      out.push({ kind: "console", relPath: file, bytes: size(file) });
+      fs4.writeFileSync(path22.join(dir, file2), consoleLines.join("\n") + "\n");
+      out.push({ kind: "console", relPath: file2, bytes: size(file2) });
     } catch {
     }
   }
@@ -4638,8 +4935,8 @@ async function applyAction(loc, step, value, ctx = {}) {
       const name = String(value ?? "");
       const names = step.values ?? (name ? [name] : []);
       const files = names.map((n2) => ctx.resolveFile?.(n2));
-      const file = files.every(Boolean);
-      if (!file) {
+      const file2 = files.every(Boolean);
+      if (!file2) {
         throw Object.assign(
           new Error(
             `this step uploads "${name || "(unnamed)"}", which is not on this machine \u2014 put a copy in .flowriki/files/`
@@ -6185,8 +6482,8 @@ async function verifySteps(opts) {
 var cachedAccName = null;
 function accNameScript2() {
   if (cachedAccName === null) {
-    const path42 = accNameScriptPath();
-    cachedAccName = fs32.readFileSync(path42, "utf8");
+    const path43 = accNameScriptPath();
+    cachedAccName = fs32.readFileSync(path43, "utf8");
   }
   return cachedAccName;
 }
@@ -6680,8 +6977,8 @@ async function fieldNames(page) {
 }
 
 // ../results/dist/chunk-LYCTVHPR.js
-import { z as z5 } from "zod";
-var RunStatusSchema = z5.enum([
+import { z as z8 } from "zod";
+var RunStatusSchema = z8.enum([
   "queued",
   "running",
   "passed",
@@ -6689,7 +6986,7 @@ var RunStatusSchema = z5.enum([
   "cancelled",
   "errored"
 ]);
-var TaskStatusSchema = z5.enum([
+var TaskStatusSchema = z8.enum([
   "queued",
   "running",
   "passed",
@@ -6698,7 +6995,7 @@ var TaskStatusSchema = z5.enum([
   "cancelled",
   "errored"
 ]);
-var FailureKindSchema = z5.enum([
+var FailureKindSchema = z8.enum([
   "not_found",
   "ambiguous",
   "timeout",
@@ -6707,30 +7004,30 @@ var FailureKindSchema = z5.enum([
   "crash",
   "unknown"
 ]);
-var RunCheckSchema = z5.object({
-  id: z5.string(),
-  assertionId: z5.string().nullable(),
-  kind: z5.string(),
-  expected: z5.string().nullable(),
-  actual: z5.string().nullable(),
-  ok: z5.boolean(),
+var RunCheckSchema = z8.object({
+  id: z8.string(),
+  assertionId: z8.string().nullable(),
+  kind: z8.string(),
+  expected: z8.string().nullable(),
+  actual: z8.string().nullable(),
+  ok: z8.boolean(),
   /** A failed soft check is reported but does not fail its step, so a run can
    *  be green and still carry findings. Stored per check rather than derived,
    *  because the flow it came from can be edited afterwards and history has to
    *  keep saying what actually happened. */
-  soft: z5.boolean().default(false),
-  detail: z5.string().nullable()
+  soft: z8.boolean().default(false),
+  detail: z8.string().nullable()
 });
-var RunStepSchema = z5.object({
-  id: z5.string(),
-  ordinal: z5.number().int().nonnegative(),
+var RunStepSchema = z8.object({
+  id: z8.string(),
+  ordinal: z8.number().int().nonnegative(),
   /** The STABLE document step id — this is what joins runs across time and
    * makes flake-rate a view over existing columns rather than a migration. */
-  stepId: z5.string(),
-  action: z5.string(),
-  targetRole: z5.string().nullable(),
-  targetName: z5.string().nullable(),
-  targetScope: z5.string().nullable(),
+  stepId: z8.string(),
+  action: z8.string(),
+  targetRole: z8.string().nullable(),
+  targetName: z8.string().nullable(),
+  targetScope: z8.string().nullable(),
   /** What the step typed, chose or pressed.
    *
    * A report that says `fill "Password"` and nothing else cannot tell you
@@ -6739,100 +7036,100 @@ var RunStepSchema = z5.object({
    *
    * NEVER set for a secret — see `secret` below. A run report is the thing
    * people paste into a ticket. */
-  value: z5.string().nullable().default(null),
+  value: z8.string().nullable().default(null),
   /** The step typed a secret, so `value` is deliberately absent rather than
    *  merely unknown. Stored, because "no value" and "a value withheld" render
    *  differently and history has to keep saying which it was. */
-  secret: z5.boolean().default(false),
-  status: z5.enum(["passed", "failed", "skipped"]),
+  secret: z8.boolean().default(false),
+  status: z8.enum(["passed", "failed", "skipped"]),
   failureKind: FailureKindSchema.nullable(),
-  detail: z5.string().nullable(),
+  detail: z8.string().nullable(),
   /** WHICH WAY FOUND IT, when the first way did not.
    *
    * A step carries several routes to its element and takes the first that
    * matches. Passing on a later one is not a failure, but it does mean the
    * page has moved under the step — and a suite that repairs itself quietly
    * drifts away from the application it tests. Null is the ordinary case. */
-  foundBy: z5.string().nullable().default(null),
-  durationMs: z5.number().int().nonnegative().nullable(),
+  foundBy: z8.string().nullable().default(null),
+  durationMs: z8.number().int().nonnegative().nullable(),
   /** Where the browser was when this step ran. Recorded on failure, and
    * frequently the whole answer — the element is missing because a step
    * before it navigated somewhere unexpected, not because it was renamed. */
-  pageUrl: z5.string().nullable().default(null),
-  pageTitle: z5.string().nullable().default(null),
-  checks: z5.array(RunCheckSchema).default([])
+  pageUrl: z8.string().nullable().default(null),
+  pageTitle: z8.string().nullable().default(null),
+  checks: z8.array(RunCheckSchema).default([])
 });
-var RunTaskSchema = z5.object({
-  id: z5.string(),
-  ordinal: z5.number().int().nonnegative(),
-  caseName: z5.string(),
-  rowId: z5.string().nullable(),
+var RunTaskSchema = z8.object({
+  id: z8.string(),
+  ordinal: z8.number().int().nonnegative(),
+  caseName: z8.string(),
+  rowId: z8.string().nullable(),
   capability: CapabilitySchema,
-  provider: z5.string(),
-  attempt: z5.number().int().positive().default(1),
-  maxAttempts: z5.number().int().positive().default(1),
+  provider: z8.string(),
+  attempt: z8.number().int().positive().default(1),
+  maxAttempts: z8.number().int().positive().default(1),
   status: TaskStatusSchema,
-  workerId: z5.string().nullable(),
+  workerId: z8.string().nullable(),
   /** Cloud provider's own session, so a failure is one click from their video. */
-  sessionId: z5.string().nullable(),
-  sessionUrl: z5.string().nullable(),
-  detail: z5.string().nullable(),
-  stepsRun: z5.number().int().nonnegative().default(0),
-  stepsTotal: z5.number().int().nonnegative().default(0),
-  durationMs: z5.number().int().nonnegative().nullable(),
-  steps: z5.array(RunStepSchema).default([])
+  sessionId: z8.string().nullable(),
+  sessionUrl: z8.string().nullable(),
+  detail: z8.string().nullable(),
+  stepsRun: z8.number().int().nonnegative().default(0),
+  stepsTotal: z8.number().int().nonnegative().default(0),
+  durationMs: z8.number().int().nonnegative().nullable(),
+  steps: z8.array(RunStepSchema).default([])
 });
-var ArtifactKindSchema = z5.enum(["screenshot", "video", "trace", "console", "har"]);
-var ArtifactSchema = z5.object({
-  id: z5.string(),
-  runId: z5.string(),
-  runStepId: z5.string().nullable(),
+var ArtifactKindSchema = z8.enum(["screenshot", "video", "trace", "console", "har"]);
+var ArtifactSchema = z8.object({
+  id: z8.string(),
+  runId: z8.string(),
+  runStepId: z8.string().nullable(),
   kind: ArtifactKindSchema,
-  relPath: z5.string(),
-  bytes: z5.number().int().nonnegative().nullable(),
-  masked: z5.boolean().default(false),
-  createdAt: z5.string()
+  relPath: z8.string(),
+  bytes: z8.number().int().nonnegative().nullable(),
+  masked: z8.boolean().default(false),
+  createdAt: z8.string()
 });
-var RunSummarySchema = z5.object({
-  id: z5.string(),
-  projectId: z5.string(),
+var RunSummarySchema = z8.object({
+  id: z8.string(),
+  projectId: z8.string(),
   /** What the run was FOR.
    *
    * `flake` is a deliberate repetition of one flow to measure how often it
    * passes. It is kept out of pass-rate statistics: a 98/100 flakiness check is
    * a useful finding, not a failing suite, and counting it as one would make
    * measuring reliability look like losing it. */
-  kind: z5.enum(["smoke", "test", "adhoc", "flake"]),
-  trigger: z5.enum(["ui", "cli", "ci"]),
+  kind: z8.enum(["smoke", "test", "adhoc", "flake"]),
+  trigger: z8.enum(["ui", "cli", "ci"]),
   status: RunStatusSchema,
-  flowId: z5.string().nullable(),
-  flowName: z5.string().nullable(),
-  gitSha: z5.string().nullable(),
-  gitBranch: z5.string().nullable(),
-  gitDirty: z5.boolean().default(false),
-  env: z5.string().nullable(),
-  concurrency: z5.number().int().positive().nullable(),
-  tasksTotal: z5.number().int().nonnegative().default(0),
-  tasksPassed: z5.number().int().nonnegative().default(0),
-  tasksFailed: z5.number().int().nonnegative().default(0),
+  flowId: z8.string().nullable(),
+  flowName: z8.string().nullable(),
+  gitSha: z8.string().nullable(),
+  gitBranch: z8.string().nullable(),
+  gitDirty: z8.boolean().default(false),
+  env: z8.string().nullable(),
+  concurrency: z8.number().int().positive().nullable(),
+  tasksTotal: z8.number().int().nonnegative().default(0),
+  tasksPassed: z8.number().int().nonnegative().default(0),
+  tasksFailed: z8.number().int().nonnegative().default(0),
   /** Rolled up from the run's tasks rather than stored on the run, so they
    * cannot drift from the step rows they describe. "9 of 12" in a list is
    * what tells a reader where a run died; "1 of 1 tasks" tells them nothing
    * until there is more than one browser in play. */
-  stepsRun: z5.number().int().nonnegative().default(0),
-  stepsTotal: z5.number().int().nonnegative().default(0),
-  queuedAt: z5.string(),
-  startedAt: z5.string().nullable(),
-  finishedAt: z5.string().nullable(),
-  durationMs: z5.number().int().nonnegative().nullable()
+  stepsRun: z8.number().int().nonnegative().default(0),
+  stepsTotal: z8.number().int().nonnegative().default(0),
+  queuedAt: z8.string(),
+  startedAt: z8.string().nullable(),
+  finishedAt: z8.string().nullable(),
+  durationMs: z8.number().int().nonnegative().nullable()
 });
 var RunDetailSchema = RunSummarySchema.extend({
-  errorMessage: z5.string().nullable(),
-  artifactsDir: z5.string().nullable(),
-  tasks: z5.array(RunTaskSchema).default([]),
+  errorMessage: z8.string().nullable(),
+  artifactsDir: z8.string().nullable(),
+  tasks: z8.array(RunTaskSchema).default([]),
   /** Screenshots and the like, addressed by `runStepId`. Kept flat rather than
    * nested inside each step: an artifact can belong to the run as a whole. */
-  artifacts: z5.array(ArtifactSchema).default([]),
+  artifacts: z8.array(ArtifactSchema).default([]),
   /** The document as it was executed — a flow, or a test case with the copies
    *  it held that day.
    *
@@ -6841,7 +7138,7 @@ var RunDetailSchema = RunSummarySchema.extend({
    * edited, and without surfacing it the promise was only half kept: the bytes
    * were there and nothing could reach them. Null for runs recorded before a
    * snapshot was taken. */
-  flowSnapshot: z5.unknown().nullable().default(null)
+  flowSnapshot: z8.unknown().nullable().default(null)
 });
 
 // ../results/dist/chunk-IW3PJWP6.js
@@ -7068,8 +7365,8 @@ var RUN_COLUMNS = `r.*,
   (SELECT COALESCE(SUM(steps_run), 0)   FROM run_task t WHERE t.run_id = r.id) AS steps_run,
   (SELECT COALESCE(SUM(steps_total), 0) FROM run_task t WHERE t.run_id = r.id) AS steps_total`;
 var SqliteStorage = class {
-  constructor(file = defaultDbPath()) {
-    this.file = file;
+  constructor(file2 = defaultDbPath()) {
+    this.file = file2;
   }
   file;
   db = null;
@@ -7540,7 +7837,7 @@ function toSummary(row) {
   };
 }
 
-// ../repository-store/dist/chunk-HTFXAD4R.js
+// ../repository-store/dist/chunk-NTWCKFD3.js
 var FLOWRIKI_DIR = ".flowriki";
 var FEATURES_DIR = `${FLOWRIKI_DIR}/features`;
 var CONFIG_PATH = `${FLOWRIKI_DIR}/config.json`;
@@ -7552,6 +7849,7 @@ var SUITES_DIR = `${FLOWRIKI_DIR}/suites`;
 var AUTH_DIR = `${FLOWRIKI_DIR}/auth`;
 var ACCOUNTS_DIR = `${AUTH_DIR}/accounts`;
 var HELPERS_DIR = `${FLOWRIKI_DIR}/helpers`;
+var LIBRARY_DIR = `${FLOWRIKI_DIR}/library`;
 function assertSlug(slug) {
   if (!/^[a-z0-9][a-z0-9-]*$/.test(slug)) throw new Error(`invalid slug: ${slug}`);
   return slug;
@@ -7807,8 +8105,8 @@ ${line}
     );
   }
 };
-function writeFileAtomic(file, contents) {
-  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+function writeFileAtomic(file2, contents) {
+  const tmp = `${file2}.tmp-${process.pid}-${Date.now()}`;
   const handle = fs23.openSync(tmp, "w");
   try {
     fs23.writeFileSync(handle, contents);
@@ -7817,7 +8115,7 @@ function writeFileAtomic(file, contents) {
     fs23.closeSync(handle);
   }
   try {
-    fs23.renameSync(tmp, file);
+    fs23.renameSync(tmp, file2);
   } catch (err) {
     fs23.rmSync(tmp, { force: true });
     throw err;
@@ -7844,13 +8142,13 @@ var Store = class {
     const out = [];
     for (const entry of fs23.readdirSync(this.featuresDir, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
-      const file = path23.join(this.featuresDir, entry.name, FEATURE_FILE);
-      if (!fs23.existsSync(file)) continue;
+      const file2 = path23.join(this.featuresDir, entry.name, FEATURE_FILE);
+      if (!fs23.existsSync(file2)) continue;
       try {
-        out.push(FeatureSchema.parse(JSON.parse(fs23.readFileSync(file, "utf8"))));
+        out.push(FeatureSchema.parse(JSON.parse(fs23.readFileSync(file2, "utf8"))));
       } catch (err) {
         this.featureProblems.push({
-          path: path23.relative(this.root, file),
+          path: path23.relative(this.root, file2),
           error: String(err instanceof Error ? err.message : err).split("\n")[0].trim(),
           recoverable: false
         });
@@ -7892,9 +8190,9 @@ var Store = class {
     for (const slug of features) {
       const dir = path23.join(this.featuresDir, slug);
       if (!fs23.existsSync(dir)) continue;
-      for (const file of fs23.readdirSync(dir)) {
-        if (!isFlowFile(file)) continue;
-        const full = path23.join(dir, file);
+      for (const file2 of fs23.readdirSync(dir)) {
+        if (!isFlowFile(file2)) continue;
+        const full = path23.join(dir, file2);
         try {
           out.push(parseFlowDocument(JSON.parse(fs23.readFileSync(full, "utf8"))));
         } catch (err) {
@@ -7923,16 +8221,16 @@ var Store = class {
    *
    * Outside `features/`, because that directory is the product and is
    * committed; a recovery copy is machine-local noise. */
-  recoveryPathFor(file) {
-    return path23.join(this.root, ".flowriki", ".recovery", path23.basename(file) + ".bak");
+  recoveryPathFor(file2) {
+    return path23.join(this.root, ".flowriki", ".recovery", path23.basename(file2) + ".bak");
   }
   /** Restore a flow file from its recovery copy. Returns false when there is
    *  none, which is the honest answer rather than an invented document. */
   recoverFlowFile(relativePath) {
-    const file = path23.join(this.root, relativePath);
-    const backup = this.recoveryPathFor(file);
+    const file2 = path23.join(this.root, relativePath);
+    const backup = this.recoveryPathFor(file2);
     if (!fs23.existsSync(backup)) return false;
-    fs23.copyFileSync(backup, file);
+    fs23.copyFileSync(backup, file2);
     return true;
   }
   /** Write a flow, atomically, keeping the previous contents recoverable.
@@ -7951,9 +8249,9 @@ var Store = class {
     const featureSlug = this.assertSlug(doc.featureId.replace(/^f_/, ""));
     const dir = path23.join(this.featuresDir, featureSlug);
     fs23.mkdirSync(dir, { recursive: true });
-    const file = path23.join(dir, `${this.assertSlug(doc.slug)}${FLOW_SUFFIX}`);
-    const destination = this.readFlowFile(file);
-    if (fs23.existsSync(file) && (!destination || destination.id !== doc.id)) {
+    const file2 = path23.join(dir, `${this.assertSlug(doc.slug)}${FLOW_SUFFIX}`);
+    const destination = this.readFlowFile(file2);
+    if (fs23.existsSync(file2) && (!destination || destination.id !== doc.id)) {
       throw new FlowConflict("the destination contains another flow or an unreadable document \u2014 choose another name or recover it first", destination?.revision ?? 0);
     }
     const current = this.getFlow(doc.id) ?? destination;
@@ -7970,21 +8268,21 @@ var Store = class {
       }
     }
     doc.revision = (current?.revision ?? doc.revision ?? 0) + 1;
-    const previousFile = current ? path23.join(this.root, this.relPath(current)) : file;
+    const previousFile = current ? path23.join(this.root, this.relPath(current)) : file2;
     if (fs23.existsSync(previousFile)) {
       const backup = this.recoveryPathFor(previousFile);
       fs23.mkdirSync(path23.dirname(backup), { recursive: true });
       fs23.copyFileSync(previousFile, backup);
       this.ensureRecoveryIgnored();
     }
-    writeFileAtomic(file, JSON.stringify(doc, null, 2) + "\n");
-    if (previousFile !== file) fs23.rmSync(previousFile);
-    return path23.relative(this.root, file);
+    writeFileAtomic(file2, JSON.stringify(doc, null, 2) + "\n");
+    if (previousFile !== file2) fs23.rmSync(previousFile);
+    return path23.relative(this.root, file2);
   }
   /** Read one flow file, or null when it is missing or unreadable. */
-  readFlowFile(file) {
+  readFlowFile(file2) {
     try {
-      return parseFlowDocument(JSON.parse(fs23.readFileSync(file, "utf8")));
+      return parseFlowDocument(JSON.parse(fs23.readFileSync(file2, "utf8")));
     } catch {
       return null;
     }
@@ -8111,8 +8409,8 @@ var Store = class {
   resolveFile(name) {
     const first = name;
     if (!first || first.includes("/") || first.includes("\\") || first.includes("..")) return void 0;
-    const file = path23.join(this.filesDir, first);
-    return fs23.existsSync(file) ? file : void 0;
+    const file2 = path23.join(this.filesDir, first);
+    return fs23.existsSync(file2) ? file2 : void 0;
   }
   // ── secret values, held by `LocalSecrets` ───────────────────────────────
   //
@@ -8239,9 +8537,9 @@ function writeMarker(root, marker, opts = {}) {
   if (!facts.clean) {
     throw new ClaimRefused("this repository has uncommitted changes \u2014 commit or stash them first");
   }
-  const file = path33.join(root, MARKER_PATH);
-  fs33.mkdirSync(path33.dirname(file), { recursive: true });
-  fs33.writeFileSync(file, JSON.stringify(marker, null, 2) + "\n");
+  const file2 = path33.join(root, MARKER_PATH);
+  fs33.mkdirSync(path33.dirname(file2), { recursive: true });
+  fs33.writeFileSync(file2, JSON.stringify(marker, null, 2) + "\n");
   git2(root, ["add", "--", MARKER_PATH]);
   git2(root, ["commit", "-m", `Bind this repository to Flowriki project ${marker.projectId}`]);
   const commit = git2(root, ["rev-parse", "HEAD"]);
@@ -8588,7 +8886,7 @@ async function executeFlow(opts) {
   for (let attempt = 1; attempt <= repeat; attempt++) {
     if (opts.signal?.aborted) break;
     const evidenceDir = runDir && repeat > 1 ? path7.join(runDir, `attempt-${String(attempt).padStart(3, "0")}`) : runDir;
-    const relativeTo = (file) => repeat > 1 ? `attempt-${String(attempt).padStart(3, "0")}/${file}` : file;
+    const relativeTo = (file2) => repeat > 1 ? `attempt-${String(attempt).padStart(3, "0")}/${file2}` : file2;
     const taskId = storage && run ? await storage.createTask(run.id, {
       caseName: repeat > 1 ? `${flow.name} \xB7 attempt ${attempt}` : flow.name,
       capability: LOCAL_CHROMIUM,
@@ -8771,10 +9069,10 @@ function report(attempts, perStep) {
     steps
   };
 }
-function sizeOf(dir, file) {
+function sizeOf(dir, file2) {
   if (!dir) return null;
   try {
-    return fs7.statSync(path7.join(dir, file)).size;
+    return fs7.statSync(path7.join(dir, file2)).size;
   } catch {
     return null;
   }
@@ -9227,10 +9525,10 @@ var RecordingCoordinator = class {
       // saveFlow bumps this to 1; a fresh document starts unrevised.
       revision: 0
     };
-    const file = this.deps.store.saveFlow(doc);
+    const file2 = this.deps.store.saveFlow(doc);
     this.draft = null;
-    const saved = { ...this.deps.store.getFlow(doc.id) ?? doc, path: file };
-    this.deps.emit({ type: "recording.stopped", flow: saved, file });
+    const saved = { ...this.deps.store.getFlow(doc.id) ?? doc, path: file2 };
+    this.deps.emit({ type: "recording.stopped", flow: saved, file: file2 });
     return this.lastResult = { ok: true, flow: saved, secrets: captured };
   }
   /** Throw the recording away: close the browser, drop the draft, write
@@ -9575,6 +9873,9 @@ function resolveCheckouts(dirs) {
   return { projects, skipped };
 }
 
+// src/engine/session.ts
+import fs12 from "fs";
+
 // ../agent-core/dist/chunk-LR7LBGCT.js
 import { WebSocket, WebSocketServer } from "ws";
 var HEARTBEAT_MS = 3e4;
@@ -9753,15 +10054,15 @@ var EventJournal = class {
 };
 var { DatabaseSync } = createRequire4(import.meta.url)("node:sqlite");
 var AgentState = class {
-  constructor(file, deviceId, commandLimit = 1e5) {
+  constructor(file2, deviceId, commandLimit = 1e5) {
     this.commandLimit = commandLimit;
-    if (!file || file === ":memory:") throw new Error("a persistent agent state file is required");
+    if (!file2 || file2 === ":memory:") throw new Error("a persistent agent state file is required");
     if (!Number.isInteger(commandLimit) || commandLimit < 1) throw new Error("invalid command capacity");
-    fs9.mkdirSync(path9.dirname(file), { recursive: true, mode: 448 });
-    const fd = fs9.openSync(file, "a", 384);
+    fs9.mkdirSync(path9.dirname(file2), { recursive: true, mode: 448 });
+    const fd = fs9.openSync(file2, "a", 384);
     fs9.closeSync(fd);
-    fs9.chmodSync(file, 384);
-    this.db = new DatabaseSync(file);
+    fs9.chmodSync(file2, 384);
+    this.db = new DatabaseSync(file2);
     try {
       this.db.exec("PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;");
       const version = Number(this.db.prepare("PRAGMA user_version").get()?.user_version);
@@ -10179,6 +10480,13 @@ import os5 from "os";
 import path10 from "path";
 import fs25 from "fs";
 import path24 from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+import fs34 from "fs";
+import path34 from "path";
+import { spawn as nodeSpawn } from "child_process";
+import fs43 from "fs";
+import os22 from "os";
+import path42 from "path";
 var NO_CHECKOUT = {
   ok: false,
   reason: "failed",
@@ -10248,12 +10556,12 @@ function repositoryHandlers({ storeFor }) {
         return { ok: false, reason: "failed", detail: "no flow document was sent" };
       }
       try {
-        const path34 = store.saveFlow(flow, {
+        const path52 = store.saveFlow(flow, {
           create: command.args["create"] === true,
           ...command.flowRevision !== void 0 ? { expectedRevision: command.flowRevision } : {}
         });
         const saved = store.getFlow(flow.id);
-        return { ok: true, result: { path: path34, revision: saved?.revision ?? null } };
+        return { ok: true, result: { path: path52, revision: saved?.revision ?? null } };
       } catch (err) {
         if (err instanceof FlowConflict) {
           return { ok: false, reason: "stale_revision", detail: err.message };
@@ -10422,11 +10730,11 @@ function historyHandlers({ storage, artifactLimit }) {
       const artifact = run.artifacts.find((a) => a.id === artifactId);
       if (!artifact) return { ok: false, reason: "failed", detail: "no such artifact on that run" };
       const dir = run.artifactsDir ?? runArtifactsDir(runId, run.projectId);
-      const file = path24.join(dir, artifact.relPath);
-      if (!isInside(dir, file) || !fs25.existsSync(file) || !isInside(fs25.realpathSync(dir), fs25.realpathSync(file))) {
+      const file2 = path24.join(dir, artifact.relPath);
+      if (!isInside(dir, file2) || !fs25.existsSync(file2) || !isInside(fs25.realpathSync(dir), fs25.realpathSync(file2))) {
         return { ok: false, reason: "failed", detail: "the artifact file is not on this machine" };
       }
-      const { size } = fs25.statSync(file);
+      const { size } = fs25.statSync(file2);
       if (size > artifactLimit) {
         return { ok: false, reason: "failed", detail: `this artifact is ${size} bytes, over the ${artifactLimit}-byte transfer limit` };
       }
@@ -10437,7 +10745,7 @@ function historyHandlers({ storage, artifactLimit }) {
           kind: artifact.kind,
           masked: artifact.masked,
           bytes: size,
-          base64: fs25.readFileSync(file).toString("base64")
+          base64: fs25.readFileSync(file2).toString("base64")
         }
       };
     }
@@ -10838,6 +11146,118 @@ function debuggingHandlers(ctx) {
     }
   };
 }
+var file = () => path34.join(flowrikiHome(), "assistant-folders.json");
+function readAll() {
+  try {
+    const parsed = JSON.parse(fs34.readFileSync(file(), "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function gitHead(folder) {
+  try {
+    const head = fs34.readFileSync(path34.join(folder, ".git", "HEAD"), "utf8").trim();
+    const ref = /^ref: (.+)$/.exec(head)?.[1];
+    if (!ref) return { commit: /^[0-9a-f]{40}$/.test(head) ? head : null, branch: null };
+    const branch = ref.replace(/^refs\/heads\//, "");
+    const loose = path34.join(folder, ".git", ref);
+    if (fs34.existsSync(loose)) return { commit: fs34.readFileSync(loose, "utf8").trim(), branch };
+    const packed = fs34.readFileSync(path34.join(folder, ".git", "packed-refs"), "utf8");
+    const line = packed.split("\n").find((l) => l.endsWith(` ${ref}`));
+    return { commit: line?.split(" ")[0] ?? null, branch };
+  } catch {
+    return { commit: null, branch: null };
+  }
+}
+function describeFolder(folder) {
+  const exists = (() => {
+    try {
+      return fs34.statSync(folder).isDirectory();
+    } catch {
+      return false;
+    }
+  })();
+  return { path: folder, exists, ...exists ? gitHead(folder) : { commit: null, branch: null } };
+}
+function folderFor(projectId) {
+  const folder = readAll()[projectId];
+  return folder ? describeFolder(folder) : null;
+}
+function setFolder(projectId, folder) {
+  const all = readAll();
+  if (folder === null) {
+    delete all[projectId];
+  } else {
+    const resolved = path34.resolve(folder.replace(/^~(?=$|\/)/, process.env["HOME"] ?? "~"));
+    if (!path34.isAbsolute(resolved)) throw new Error("give the folder's full path");
+    if (!describeFolder(resolved).exists) throw new Error(`there is no folder at ${resolved} on this computer`);
+    if (resolved === path34.parse(resolved).root || resolved === process.env["HOME"]) throw new Error("link the project's own folder, not the whole disk or home folder");
+    all[projectId] = resolved;
+  }
+  fs34.mkdirSync(path34.dirname(file()), { recursive: true, mode: 448 });
+  fs34.writeFileSync(file(), JSON.stringify(all, null, 2), { mode: 384 });
+  return folder === null ? null : folderFor(projectId);
+}
+var MAX_PROMPT = 4e3;
+function assistantHandlers({ deps }) {
+  const assistant = deps.assistant;
+  if (!assistant) return {};
+  return {
+    "assistant.status": async () => ({
+      ok: true,
+      result: { ...await assistant.status(), busy: assistant.busy() }
+    }),
+    "assistant.connect": async (_command, _project, emit) => {
+      const started = assistant.connect(emit);
+      return started.started ? { ok: true, result: { started: true } } : { ok: false, reason: "busy", detail: started.detail ?? "could not start the sign-in" };
+    },
+    "assistant.ask": async (command, project, emit) => {
+      const prompt = typeof command.args["prompt"] === "string" ? command.args["prompt"].trim() : "";
+      if (!prompt) return { ok: false, reason: "failed", detail: "there is nothing to ask" };
+      if (prompt.length > MAX_PROMPT) {
+        return { ok: false, reason: "failed", detail: `keep it under ${MAX_PROMPT} characters` };
+      }
+      const sessionId = command.args["sessionId"];
+      if (sessionId !== void 0 && !(typeof sessionId === "string" && /^[\w-]{8,100}$/.test(sessionId))) {
+        return { ok: false, reason: "failed", detail: "that conversation id is not valid" };
+      }
+      const status2 = await assistant.status();
+      if (!status2.installed) return { ok: false, reason: "failed", detail: status2.detail ?? "the assistant is not installed on this machine" };
+      if (!status2.signedIn) return { ok: false, reason: "failed", detail: "the assistant is not signed in on this machine" };
+      const askId = randomUUID2();
+      const linked = folderFor(project.id);
+      const mode = command.args["mode"] === "ask" ? "ask" : command.args["mode"] === "do" ? "do" : void 0;
+      const started = assistant.ask({
+        askId,
+        prompt,
+        projectId: project.id,
+        projectName: project.name,
+        ...linked?.exists ? { folder: linked.path } : {},
+        ...mode ? { mode } : {},
+        ...typeof sessionId === "string" ? { sessionId } : {},
+        emit
+      });
+      return started.started ? { ok: true, result: { askId } } : { ok: false, reason: "busy", detail: started.detail ?? "the assistant is busy" };
+    },
+    /** Which folder on this computer holds the project's code — read with no
+     *  `path`, linked with a path, unlinked with null. */
+    "assistant.folder": async (command, project) => {
+      try {
+        if (command.args["path"] === void 0) return { ok: true, result: { folder: folderFor(project.id) } };
+        const asked = command.args["path"];
+        const folder = setFolder(project.id, asked === null ? null : String(asked));
+        return { ok: true, result: { folder } };
+      } catch (error) {
+        return { ok: false, reason: "failed", detail: error.message };
+      }
+    },
+    "assistant.cancel": async (command) => {
+      const askId = String(command.args["askId"] ?? "");
+      return assistant.cancel(askId) ? { ok: true, result: { cancelled: true } } : { ok: false, reason: "failed", detail: "that question is not running" };
+    }
+  };
+}
 function buildHandlers(deps) {
   const context = {
     deps,
@@ -10864,9 +11284,322 @@ function buildHandlers(deps) {
     ...historyHandlers(context),
     ...executionHandlers(context),
     ...recordingHandlers(context),
+    ...assistantHandlers(context),
     ...debug
   };
 }
+var MCP_SERVER_NAME = "flowriki";
+var TOOL_PREFIX = `mcp__${MCP_SERVER_NAME}__`;
+var SHOWN_KEYS = ["action", "role", "name", "kind", "title", "flow", "feature", "folder", "case", "op"];
+function describeToolInput(input) {
+  if (!input || typeof input !== "object") return "";
+  const record = input;
+  const parts = [];
+  for (const key of SHOWN_KEYS) {
+    const value = record[key];
+    if (typeof value === "string" && value) parts.push(value.length > 80 ? `${value.slice(0, 77)}\u2026` : value);
+  }
+  return parts.join(" \xB7 ");
+}
+var clip = (value, max = 100) => value.length > max ? `${value.slice(0, max - 1)}\u2026` : value;
+function toolArgs(tool, input) {
+  if (!input || typeof input !== "object") return {};
+  const record = input;
+  const out = {};
+  for (const key of ["action", "role", "name", "kind", "op", "within", "title", "flow", "feature", "folder", "startPath", "helperId", "saveAs", "signIn"]) {
+    const value = record[key];
+    if (typeof value === "string" && value) out[key] = clip(value);
+  }
+  for (const key of ["nth", "number"]) {
+    const value = record[key];
+    if (typeof value === "number" && Number.isFinite(value)) out[key] = value;
+  }
+  if (record["newBranch"] === true) out["newBranch"] = true;
+  if (tool === "add_check" && typeof record["value"] === "string") out["value"] = clip(record["value"], 120);
+  if (Array.isArray(record["after"])) {
+    out["after"] = record["after"].filter((v) => typeof v === "string").slice(0, 5).map((v) => clip(v));
+  }
+  if (Array.isArray(record["rows"])) {
+    out["flows"] = record["rows"].map((row) => row && typeof row === "object" ? row["flow"] : void 0).filter((v) => typeof v === "string").slice(0, 12).map((v) => clip(v));
+  }
+  return out;
+}
+function parseAuthStatus(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return {
+      signedIn: parsed.loggedIn === true,
+      method: typeof parsed.authMethod === "string" ? parsed.authMethod : null,
+      plan: typeof parsed.subscriptionType === "string" ? parsed.subscriptionType : null
+    };
+  } catch {
+    return { signedIn: false, method: null, plan: null };
+  }
+}
+var ASK_MODE_TOOLS = [
+  "list_projects",
+  "project_catalog",
+  "project_brief",
+  "knowledge_search",
+  "knowledge_read",
+  "sources",
+  "requirements",
+  "find_similar_cases",
+  "library_cases",
+  "test_cycles",
+  "bugs",
+  "list_my_branches",
+  "integrations"
+];
+function buildAskArgs(opts) {
+  const ask = opts.mode === "ask";
+  const guidance = [
+    `You are the Flowriki assistant for the project "${opts.projectName}" (id ${opts.projectId}). Use the Flowriki tools, and pass projectId "${opts.projectId}" wherever a tool takes one. Start with project_brief: it is this project's memory.`,
+    ask ? "ASK MODE: answer the question; change nothing. Cite what you rely on as [[testCase:TC-12]], [[source:src_x@v2]], [[requirement:req_x]], [[knowledge:features/checkout.md]], [[automation:tc_x]], [[cycle:cyc_x]], [[bug:BUG-3]] or [[file:path/in/repo.ts]]." : "DO MODE: do what is asked, on Claude's working branch, for a person to review. Ask in the chat and wait before publishing, deleting, or sending anything to another system. End by writing a short summary of what you did with write_knowledge (memory/sessions/<date>-<topic>.md, append) so the next session knows.",
+    opts.folder ? `The project's code is in ${opts.folder}. Read it with Read, Grep and Glob when it helps; you cannot change it.` : ""
+  ].filter(Boolean).join("\n");
+  const flowriki = ask ? ASK_MODE_TOOLS.map((t) => `mcp__${MCP_SERVER_NAME}__${t}`) : [`mcp__${MCP_SERVER_NAME}`];
+  const files = opts.folder ? ["Read", "Grep", "Glob"] : [];
+  return [
+    "-p",
+    opts.prompt,
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    "--mcp-config",
+    opts.mcpConfigPath,
+    "--strict-mcp-config",
+    // No built-in tools but reading files in the linked folder — no shell, no
+    // edits, no web.
+    "--tools",
+    files.join(","),
+    ...opts.folder ? ["--add-dir", opts.folder] : [],
+    // Only these, and anything else is denied rather than asked about: there
+    // is nobody at a terminal to answer.
+    "--allowedTools",
+    [...flowriki, ...files].join(","),
+    "--permission-mode",
+    "dontAsk",
+    "--append-system-prompt",
+    guidance,
+    ...opts.sessionId ? ["--resume", opts.sessionId] : []
+  ];
+}
+function eventsFromLine(askId, line) {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return [];
+  }
+  const out = [];
+  if (parsed.type === "system" && parsed.subtype === "init" && parsed.session_id) {
+    out.push({ name: "assistant.session", data: { askId, sessionId: parsed.session_id } });
+  }
+  if (parsed.type === "assistant") {
+    for (const block of parsed.message?.content ?? []) {
+      if (block.type === "text" && block.text?.trim()) {
+        out.push({ name: "assistant.text", data: { askId, text: block.text } });
+      } else if (block.type === "tool_use" && block.name) {
+        const tool = block.name.replace(TOOL_PREFIX, "");
+        out.push({
+          name: "assistant.tool",
+          data: {
+            askId,
+            tool,
+            target: describeToolInput(block.input),
+            args: toolArgs(tool, block.input),
+            ...block.id ? { id: block.id } : {}
+          }
+        });
+      }
+    }
+  }
+  if (parsed.type === "user") {
+    for (const block of parsed.message?.content ?? []) {
+      if (block.type !== "tool_result" || !block.tool_use_id) continue;
+      const raw = typeof block.content === "string" ? block.content : Array.isArray(block.content) ? block.content.map((part) => part && typeof part === "object" ? String(part.text ?? "") : "").join("\n") : "";
+      const first = raw.split("\n").map((l) => l.trim()).find(Boolean) ?? "";
+      const changeId = /\/changes\/(chg_[A-Za-z0-9]+)/.exec(raw)?.[1];
+      out.push({
+        name: "assistant.toolResult",
+        data: { askId, id: block.tool_use_id, ok: block.is_error !== true, summary: clip(first, 240), ...changeId ? { changeId } : {} }
+      });
+    }
+  }
+  if (parsed.type === "result") {
+    out.push({
+      name: "assistant.done",
+      data: {
+        askId,
+        ok: parsed.is_error !== true,
+        result: typeof parsed.result === "string" ? parsed.result : "",
+        ...parsed.session_id ? { sessionId: parsed.session_id } : {}
+      }
+    });
+  }
+  return out;
+}
+function createClaudeCli(options) {
+  const spawn2 = options.spawn ?? nodeSpawn;
+  const binary = options.binary ?? process.env["FLOWRIKI_CLAUDE_BIN"] ?? "claude";
+  const maxAskMs = options.maxAskMs ?? 30 * 6e4;
+  const scratchRoot2 = options.scratchRoot ?? path42.join(os22.tmpdir(), "flowriki-claude");
+  let current = null;
+  let cancelled = null;
+  function capture(args, timeoutMs = 15e3) {
+    return new Promise((resolve) => {
+      let out = "", err = "", settled = false;
+      const finish = (code, failed) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve({ code, out, err, failed });
+      };
+      let child;
+      try {
+        child = spawn2(binary, args, { stdio: ["ignore", "pipe", "pipe"] });
+      } catch {
+        return resolve({ code: null, out: "", err: "", failed: true });
+      }
+      const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        finish(null, true);
+      }, timeoutMs);
+      child.stdout?.on("data", (chunk) => {
+        out += chunk.toString();
+      });
+      child.stderr?.on("data", (chunk) => {
+        err += chunk.toString();
+      });
+      child.on("error", () => finish(null, true));
+      child.on("close", (code) => finish(code, false));
+    });
+  }
+  return {
+    async status() {
+      const version = await capture(["--version"]);
+      if (version.failed || version.code !== 0) {
+        return { installed: false, version: null, signedIn: false, method: null, plan: null, detail: "The assistant\u2019s command-line tool was not found on this machine." };
+      }
+      const auth = await capture(["auth", "status", "--json"]);
+      const parsed = parseAuthStatus(auth.out);
+      return { installed: true, version: version.out.trim().split(/\s+/)[0] ?? null, ...parsed };
+    },
+    connect(emit) {
+      if (current) return { started: false, detail: "The assistant is busy answering a question." };
+      let child;
+      try {
+        child = spawn2(binary, ["auth", "login"], { stdio: ["ignore", "pipe", "pipe"] });
+      } catch {
+        return { started: false, detail: "The assistant\u2019s command-line tool could not be started." };
+      }
+      let finished = false;
+      const done = async (detail) => {
+        if (finished) return;
+        finished = true;
+        const status2 = await this.status();
+        emit("assistant.connect.finished", { signedIn: status2.signedIn, ...detail ? { detail } : {} });
+      };
+      const timer = setTimeout(() => {
+        child.kill("SIGTERM");
+        void done("The sign-in was not completed in time.");
+      }, 5 * 6e4);
+      timer.unref?.();
+      child.on("error", () => {
+        clearTimeout(timer);
+        void done("The assistant\u2019s command-line tool could not be started.");
+      });
+      child.on("close", () => {
+        clearTimeout(timer);
+        void done();
+      });
+      return { started: true };
+    },
+    ask(ask) {
+      if (current) return { started: false, detail: "The assistant is already answering a question on this machine." };
+      fs43.mkdirSync(scratchRoot2, { recursive: true, mode: 448 });
+      const dir = fs43.mkdtempSync(path42.join(scratchRoot2, "ask-"));
+      const mcpConfigPath = path42.join(dir, "mcp.json");
+      fs43.writeFileSync(
+        mcpConfigPath,
+        JSON.stringify({ mcpServers: { [MCP_SERVER_NAME]: { command: options.mcp.command, args: options.mcp.args } } }),
+        { mode: 384 }
+      );
+      let child;
+      try {
+        child = spawn2(
+          binary,
+          buildAskArgs({
+            prompt: ask.prompt,
+            mcpConfigPath,
+            projectId: ask.projectId,
+            projectName: ask.projectName,
+            ...ask.sessionId ? { sessionId: ask.sessionId } : {},
+            ...ask.folder ? { folder: ask.folder } : {},
+            ...ask.mode ? { mode: ask.mode } : {}
+          }),
+          // THE SCRATCH FOLDER, not the project: nothing here to read or write.
+          { cwd: dir, stdio: ["ignore", "pipe", "pipe"] }
+        );
+      } catch {
+        fs43.rmSync(dir, { recursive: true, force: true });
+        return { started: false, detail: "The assistant\u2019s command-line tool could not be started." };
+      }
+      current = { askId: ask.askId, child };
+      let buffer = "", stderr = "", sawDone = false, ended = false;
+      const handleLine = (line) => {
+        for (const event of eventsFromLine(ask.askId, line)) {
+          if (event.name === "assistant.done") sawDone = true;
+          ask.emit(event.name, event.data);
+        }
+      };
+      const end = (ok, detail) => {
+        if (ended) return;
+        ended = true;
+        clearTimeout(timer);
+        if (buffer.trim()) handleLine(buffer);
+        if (!sawDone) ask.emit("assistant.done", { askId: ask.askId, ok, result: detail });
+        current = null;
+        fs43.rmSync(dir, { recursive: true, force: true });
+      };
+      const timer = setTimeout(() => {
+        child.kill("SIGTERM");
+        end(false, `Stopped after ${Math.max(1, Math.round(maxAskMs / 6e4))} minutes. Whatever it saved so far is on the Branches page \u2014 send \u201Ccontinue\u201D to carry on.`);
+      }, maxAskMs);
+      timer.unref?.();
+      child.stdout?.on("data", (chunk) => {
+        buffer += chunk.toString();
+        let at;
+        while ((at = buffer.indexOf("\n")) >= 0) {
+          handleLine(buffer.slice(0, at));
+          buffer = buffer.slice(at + 1);
+        }
+      });
+      child.stderr?.on("data", (chunk) => {
+        stderr = (stderr + chunk.toString()).slice(-2e3);
+      });
+      child.on("error", () => end(false, "The assistant\u2019s command-line tool could not be started."));
+      child.on(
+        "close",
+        (code) => end(
+          code === 0,
+          cancelled === ask.askId ? "Stopped." : code === 0 ? "" : stderr.trim().split("\n").slice(-3).join(" ") || `The assistant stopped (exit ${code ?? "?"}).`
+        )
+      );
+      return { started: true };
+    },
+    cancel(askId) {
+      if (!current || current.askId !== askId) return false;
+      cancelled = askId;
+      current.child.kill("SIGTERM");
+      const child = current.child;
+      setTimeout(() => child.kill("SIGKILL"), 3e3).unref?.();
+      return true;
+    },
+    busy: () => current !== null
+  };
+}
 function createAgentRuntime(options) {
   const lease = new BrowserLease();
   let journal = null;
@@ -10995,6 +11728,7 @@ function createAgentRuntime(options) {
     const handlers = buildHandlers({
       lease,
       authenticationReuse: keptSignIns,
+      ...options.mcpServer ? { assistant: createClaudeCli({ mcp: options.mcpServer }) } : {},
       storeFor: (r) => new Store(r),
       ...options.storage ? { storage: options.storage } : {},
       recorder,
@@ -11053,24 +11787,24 @@ import fs11 from "fs";
 import os6 from "os";
 function takeLock(env = process.env) {
   ensureDataDir(env);
-  const file = lockPath(env);
+  const file2 = lockPath(env);
   const mine = { pid: process.pid, since: (/* @__PURE__ */ new Date()).toISOString(), host: os6.hostname() };
   for (let attempt = 0; attempt < 2; attempt += 1) {
     try {
-      fs11.writeFileSync(file, JSON.stringify(mine), { flag: "wx", mode: 384 });
-      return { ok: true, lock: { release: () => releaseLock(file, mine.pid) } };
+      fs11.writeFileSync(file2, JSON.stringify(mine), { flag: "wx", mode: 384 });
+      return { ok: true, lock: { release: () => releaseLock(file2, mine.pid) } };
     } catch {
-      const held = readLock(file);
+      const held = readLock(file2);
       if (!held) {
         try {
-          fs11.rmSync(file, { force: true });
+          fs11.rmSync(file2, { force: true });
         } catch {
         }
         continue;
       }
       if (held.host === mine.host && !alive(held.pid)) {
         try {
-          fs11.rmSync(file, { force: true });
+          fs11.rmSync(file2, { force: true });
         } catch {
         }
         continue;
@@ -11078,11 +11812,11 @@ function takeLock(env = process.env) {
       return { ok: false, held };
     }
   }
-  return { ok: false, held: readLock(file) ?? { pid: -1, since: "", host: "unknown" } };
+  return { ok: false, held: readLock(file2) ?? { pid: -1, since: "", host: "unknown" } };
 }
-function readLock(file) {
+function readLock(file2) {
   try {
-    const held = JSON.parse(fs11.readFileSync(file, "utf8"));
+    const held = JSON.parse(fs11.readFileSync(file2, "utf8"));
     return typeof held.pid === "number" ? { pid: held.pid, since: held.since ?? "", host: held.host ?? "" } : null;
   } catch {
     return null;
@@ -11097,17 +11831,26 @@ function alive(pid) {
     return error.code === "EPERM";
   }
 }
-function releaseLock(file, pid) {
-  const held = readLock(file);
+function releaseLock(file2, pid) {
+  const held = readLock(file2);
   if (held?.pid === pid) {
     try {
-      fs11.rmSync(file, { force: true });
+      fs11.rmSync(file2, { force: true });
     } catch {
     }
   }
 }
 
 // src/engine/session.ts
+function mcpServer() {
+  const script2 = process.argv[1];
+  if (!script2) return null;
+  try {
+    return { command: process.execPath, args: [fs12.realpathSync(script2), "mcp"] };
+  } catch {
+    return null;
+  }
+}
 async function start(options = {}) {
   let service;
   try {
@@ -11162,6 +11905,10 @@ async function start(options = {}) {
     stateFile: ledgerPath(connection.deviceId),
     projects,
     storage,
+    // THE SAME PROGRAM, started again as `mcp`, so Claude's tools are the ones
+    // this very install provides — not whatever `flowriki-agent` happens to be
+    // first on somebody's PATH.
+    ...mcpServer() ? { mcpServer: mcpServer() } : {},
     onEvent: (event) => options.onProgress?.({ kind: event.name, message: "", detail: event.data })
   });
   const link = new AgentLink({
@@ -11271,6 +12018,7 @@ export {
   connect,
   RecordedStepSchema,
   mirrorCheckTargets,
+  similarity,
   runtimeValue,
   authenticationResolver,
   checkAssertion,