@raisindb/client 0.5.8 → 0.5.10

package/dist/index.js

@@ -27,6 +27,8 @@ var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  AgentRunsApi: () => AgentRunsApi,
+  AgentRunsWsApi: () => AgentRunsWsApi,
   AllNodeEventTypes: () => AllNodeEventTypes,
   Archetypes: () => Archetypes,
   AuthManager: () => AuthManager,
@@ -67,6 +69,7 @@ __export(src_exports, {
   McpClient: () => McpClient,
   MemoryTokenStorage: () => MemoryTokenStorage,
   NodeBuilder: () => NodeBuilder,
+  NodeDevApi: () => NodeDevApi,
   NodeEventType: () => NodeEventType,
   NodeFileSource: () => NodeFileSource,
   NodeHelpers: () => NodeHelpers,
@@ -96,6 +99,7 @@ __export(src_exports, {
   UploadErrorCode: () => UploadErrorCode,
   UploadManager: () => UploadManager,
   Uploader: () => Uploader,
+  VisitorChatError: () => VisitorChatError,
   WorkspaceClient: () => WorkspaceClient,
   WorkspaceManager: () => WorkspaceManager,
   calculateChunkCount: () => calculateChunkCount,
@@ -117,6 +121,7 @@ __export(src_exports, {
   createSqlHandler: () => createSqlHandler,
   createSubscriptionAdapter: () => createSubscriptionAdapter,
   decodeMessage: () => decodeMessage,
+  defaultVisitorSessionStore: () => defaultVisitorSessionStore,
   encodeMessage: () => encodeMessage,
   getChunkRange: () => getChunkRange,
   getContentType: () => getContentType,
@@ -134,12 +139,14 @@ __export(src_exports, {
   isTerminalEvent: () => isTerminalEvent,
   isWebSocketClient: () => isWebSocketClient,
   logger: () => logger,
+  newControlId: () => newControlId,
   normalizeHomePath: () => normalizeHomePath,
   projectPlansFromMessages: () => projectPlansFromMessages,
   readTokensFromFragment: () => readTokensFromFragment,
   rowsToObjects: () => rowsToObjects,
   setLogLevel: () => setLogLevel,
   sleep: () => sleep,
+  subjectOf: () => subjectOf,
   useConversation: () => useConversation,
   useConversationList: () => useConversationList,
   useFlow: () => useFlow,
@@ -953,12 +960,23 @@ var RequestType = /* @__PURE__ */ ((RequestType2) => {
   RequestType2["FlowCancel"] = "flow_cancel";
   RequestType2["FlowSubscribeEvents"] = "flow_subscribe_events";
   RequestType2["FlowUnsubscribeEvents"] = "flow_unsubscribe_events";
+  RequestType2["AgentRunCreate"] = "agent_run_create";
+  RequestType2["AgentRunGet"] = "agent_run_get";
+  RequestType2["AgentRunBySubject"] = "agent_run_by_subject";
+  RequestType2["AgentRunList"] = "agent_run_list";
+  RequestType2["AgentRunEvents"] = "agent_run_events";
+  RequestType2["AgentRunSubscribe"] = "agent_run_subscribe";
+  RequestType2["AgentRunUnsubscribe"] = "agent_run_unsubscribe";
+  RequestType2["AgentRunControl"] = "agent_run_control";
+  RequestType2["AgentRunChildren"] = "agent_run_children";
   RequestType2["FunctionInvoke"] = "function_invoke";
   RequestType2["FunctionInvokeSync"] = "function_invoke_sync";
   RequestType2["ScheduledInvocationCreate"] = "scheduled_invocation_create";
   RequestType2["ScheduledInvocationCancel"] = "scheduled_invocation_cancel";
   RequestType2["ScheduledInvocationList"] = "scheduled_invocation_list";
   RequestType2["ScheduledInvocationGet"] = "scheduled_invocation_get";
+  RequestType2["VisitorChatStart"] = "visitor_chat_start";
+  RequestType2["VisitorChatSend"] = "visitor_chat_send";
   return RequestType2;
 })(RequestType || {});
 var ResponseStatus = /* @__PURE__ */ ((ResponseStatus2) => {
@@ -1242,7 +1260,8 @@ var EventHandler = class {
     this.filterSubscriptions.set(hash, {
       serverId: subscriptionId,
       filters: {},
-      callbacks: /* @__PURE__ */ new Set([callback])
+      callbacks: /* @__PURE__ */ new Set([callback]),
+      synthetic: true
     });
     this.subscriptions.set(subscriptionId, hash);
     this.callbackToHash.set(callback, hash);
@@ -1277,11 +1296,12 @@ var EventHandler = class {
   async restoreSubscriptions(options) {
     if (!options?.retry) {
       for (const entry of this.filterSubscriptions.values()) {
+        if (entry.synthetic) continue;
         this.subscriptions.delete(entry.serverId);
         entry.restorePending = true;
       }
     }
-    const entriesToRestore = Array.from(this.filterSubscriptions.entries()).filter(([, entry]) => entry.restorePending);
+    const entriesToRestore = Array.from(this.filterSubscriptions.entries()).filter(([, entry]) => entry.restorePending && !entry.synthetic);
     let failureCount = 0;
     let lastError;
     for (const [hash, entry] of entriesToRestore) {
@@ -3437,6 +3457,417 @@ function createAsyncQueue() {
   };
 }
 
+// src/agent-run-children.ts
+function spawnBody(o) {
+  return {
+    objective: o.objective,
+    budgets: o.budgets,
+    on_exceeded: o.onExceeded,
+    spawn_key: o.spawnKey,
+    subject: o.subject,
+    as_agent: o.asAgent,
+    agent_ref: o.agentRef,
+    input: o.input ?? null,
+    executor_config: o.executorConfig,
+    reducer: o.reducer,
+    inherit_reducer: o.inheritReducer ?? false
+  };
+}
+function checkpointBody(o) {
+  return {
+    fence: o.fence,
+    operation_id: o.operationId,
+    reason: o.reason,
+    summary: o.summary,
+    transcript_cutoff: o.transcriptCutoff,
+    state: o.state,
+    large_refs: o.largeRefs ?? []
+  };
+}
+
+// src/agent-runs.ts
+function createRunBody(options) {
+  return {
+    subject: options.subject,
+    branch: options.branch,
+    agent_ref: options.agentRef,
+    create_key: options.createKey,
+    budgets: options.budgets,
+    input: options.input ?? null,
+    reducer: options.reducer,
+    executor_config: options.executorConfig,
+    control_capability: options.controlCapability,
+    as_agent: options.asAgent
+  };
+}
+function subjectOf(subject) {
+  if (typeof subject !== "string") return subject;
+  const cut = subject.indexOf(":/");
+  if (cut <= 0) throw new Error(`subject must be "workspace:/path", got "${subject}"`);
+  return { workspace: subject.slice(0, cut), path: subject.slice(cut + 1) };
+}
+var controlCounter = 0;
+function newControlId(prefix = "ctl") {
+  controlCounter += 1;
+  const rand = Math.random().toString(36).slice(2, 10);
+  return `${prefix}-${Date.now().toString(36)}-${controlCounter}-${rand}`;
+}
+var AgentRunsApi = class {
+  constructor(repository, transport) {
+    this.repository = repository;
+    this.transport = transport;
+  }
+  base(runId, rest = "") {
+    const repo = encodeURIComponent(this.repository);
+    const run = runId ? `/${encodeURIComponent(runId)}` : "";
+    return `/api/agent-runs/${repo}${run}${rest}`;
+  }
+  /** Create a run, or get back the subject's live run. */
+  create(options) {
+    return this.transport.request("POST", this.base(), createRunBody(options));
+  }
+  /** Every run about `subject` you may see, newest (the live one) first. */
+  bySubject(subject, limit = 20) {
+    const s = subjectOf(subject);
+    const q = new URLSearchParams({ subject: `${s.workspace}:${s.path ?? ""}`, limit: String(limit) });
+    if (s.node_id) q.set("subject_node_id", s.node_id);
+    return this.transport.request("GET", `${this.base()}?${q.toString()}`);
+  }
+  /** Read a run (record + effective projection). */
+  get(runId) {
+    return this.transport.request("GET", this.base(runId));
+  }
+  /** Your runs in one status (default "running"). */
+  list(status = "running", limit = 50) {
+    return this.transport.request("GET", `${this.base()}?status=${status}&limit=${limit}`);
+  }
+  /** Durable events after `afterSeq` (gap-free; page with the last seq). */
+  events(runId, afterSeq = 0, limit = 500) {
+    return this.transport.request("GET", this.base(runId, `/events?after_seq=${afterSeq}&limit=${limit}`));
+  }
+  /** Any control. Retrying with the same `controlId` is a no-op. */
+  control(runId, command, controlId = newControlId(command.command), capability) {
+    return this.transport.request("POST", this.base(runId, "/control"), {
+      control_id: controlId,
+      command,
+      capability
+    });
+  }
+  stop(runId, reason, controlId) {
+    return this.control(runId, { command: "stop", reason }, controlId);
+  }
+  pause(runId, controlId) {
+    return this.control(runId, { command: "pause" }, controlId);
+  }
+  resume(runId, controlId) {
+    return this.control(runId, { command: "resume" }, controlId);
+  }
+  /** Queue input for the run's next safe boundary. */
+  steer(runId, input, controlId) {
+    return this.control(runId, { command: "steer", input }, controlId);
+  }
+  /** Decide an approval request; the digest ties it to one changeset. */
+  approve(runId, requestId, subjectDigest, reject, controlId) {
+    const decision = reject ? { decision: "reject", reason: reject.reason } : { decision: "approve" };
+    return this.control(
+      runId,
+      { command: "approve", request_id: requestId, decision, subject_digest: subjectDigest },
+      controlId
+    );
+  }
+  /** Answer an input request. */
+  answer(runId, requestId, value, controlId) {
+    return this.control(runId, { command: "provide_input", request_id: requestId, value }, controlId);
+  }
+  /**
+   * Stream the run's events: replay after `afterSeq`, then live. Ends after
+   * the run's terminal event. Resume after a disconnect with the last `seq`.
+   */
+  async *stream(runId, afterSeq = 0, signal) {
+    const response = await this.transport.fetch(
+      this.transport.url(this.base(runId, `/stream?after_seq=${afterSeq}`)),
+      { headers: { ...this.transport.headers(), Accept: "text/event-stream" }, signal }
+    );
+    if (!response.ok || !response.body) {
+      throw new Error(`agent run stream failed: ${response.status} ${await response.text()}`);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (; ; ) {
+      const { value, done } = await reader.read();
+      if (done) return;
+      buffer += decoder.decode(value, { stream: true });
+      let cut;
+      while ((cut = buffer.indexOf("\n\n")) >= 0) {
+        const block = buffer.slice(0, cut);
+        buffer = buffer.slice(cut + 2);
+        let event = "message";
+        let data = "";
+        for (const line of block.split("\n")) {
+          if (line.startsWith("event:")) event = line.slice(6).trim();
+          else if (line.startsWith("data:")) data += line.slice(5).trim();
+        }
+        if (event === "end") return;
+        if (event === "error") throw new Error(`agent run stream error: ${data}`);
+        if (event === "run-event" && data) yield JSON.parse(data);
+      }
+    }
+  }
+  // ---- client-driven runs -------------------------------------------------
+  /** Take the lease of a queued client-driven run. */
+  acquire(runId) {
+    return this.transport.request("POST", this.base(runId, "/lease/acquire"), {});
+  }
+  renew(runId, fence) {
+    return this.transport.request("POST", this.base(runId, "/lease/renew"), { fence });
+  }
+  release(runId, fence) {
+    return this.transport.request("POST", this.base(runId, "/lease/release"), { fence });
+  }
+  /** Begin an operation; returns the active operation (its `op_id`). */
+  begin(runId, fence, op) {
+    return this.transport.request("POST", this.base(runId, "/operations"), { fence, ...op });
+  }
+  /** Record an operation's result. */
+  finish(runId, fence, opId, result) {
+    return this.transport.request("POST", this.base(runId, "/operations/finish"), { fence, op_id: opId, ...result });
+  }
+  /** Open approval/input requests and wait (`kind: "approval" | "input"`). */
+  wait(runId, fence, requests) {
+    return this.transport.request("POST", this.base(runId, "/wait"), { fence, requests });
+  }
+  /** End a client-driven run. */
+  complete(runId, fence, status, outcome) {
+    return this.transport.request("POST", this.base(runId, "/complete"), { fence, status, outcome });
+  }
+  // ── Child runs, mailbox, checkpoints, usage ──────────────────────────────
+  /** Spawn a child with a typed objective; its budgets come out of this run's. */
+  spawnChild(runId, options) {
+    const q = options.branch ? `?branch=${encodeURIComponent(options.branch)}` : "";
+    return this.transport.request("POST", this.base(runId, `/children${q}`), spawnBody(options));
+  }
+  /** Every child of a run: the parent's link plus the child's live status. */
+  children(runId) {
+    return this.transport.request("GET", this.base(runId, "/children"));
+  }
+  /** Inspect one child: record, events after `afterSeq`, usage, checkpoint. */
+  inspectChild(runId, childId, afterSeq = 0, limit = 200) {
+    const rest = `/children/${encodeURIComponent(childId)}?after_seq=${afterSeq}&limit=${limit}`;
+    return this.transport.request("GET", this.base(runId, rest));
+  }
+  /** Message, steer, interrupt or resume a child (idempotent per `controlId`). */
+  controlChild(runId, childId, action, controlId = newControlId(action.action)) {
+    const rest = `/children/${encodeURIComponent(childId)}/control`;
+    return this.transport.request("POST", this.base(runId, rest), { control_id: controlId, ...action });
+  }
+  messageChild(runId, childId, message, controlId) {
+    return this.controlChild(runId, childId, { action: "message", message }, controlId);
+  }
+  steerChild(runId, childId, input, controlId) {
+    return this.controlChild(runId, childId, { action: "steer", input }, controlId);
+  }
+  interruptChild(runId, childId, reason, mode = "stop", controlId) {
+    return this.controlChild(runId, childId, { action: "interrupt", mode, reason }, controlId);
+  }
+  /** A client-driven parent waits (under its lease) for a child's hand-back. */
+  waitChild(runId, childId, fence, expiresAtMs) {
+    const rest = `/children/${encodeURIComponent(childId)}/wait`;
+    return this.transport.request("POST", this.base(runId, rest), { fence, expires_at_ms: expiresAtMs });
+  }
+  /** Unacknowledged mailbox items (hand-backs and child messages). */
+  mailbox(runId) {
+    return this.transport.request("GET", this.base(runId, "/mailbox"));
+  }
+  /** Acknowledge mailbox items up to `upTo`. */
+  ackMailbox(runId, upTo) {
+    return this.transport.request("POST", this.base(runId, "/mailbox/ack"), { up_to: upTo });
+  }
+  /** A child posts a message to its parent's mailbox (idempotent per id). */
+  postToParent(runId, messageId, message) {
+    return this.transport.request("POST", this.base(runId, "/post-to-parent"), { message_id: messageId, message });
+  }
+  /** Write a structured checkpoint (compaction keeps state, not prose). */
+  checkpoint(runId, options) {
+    return this.transport.request("POST", this.base(runId, "/checkpoints"), checkpointBody(options));
+  }
+  /** Read a checkpoint (default: latest) with its structured state. */
+  readCheckpoint(runId, checkpointNo) {
+    return this.transport.request("GET", this.base(runId, `/checkpoints/${checkpointNo ?? "latest"}`));
+  }
+  /** Usage accounting: own, children, reserved, spare. */
+  usage(runId) {
+    return this.transport.request("GET", this.base(runId, "/usage"));
+  }
+};
+
+// src/agent-runs-ws.ts
+var TERMINAL = ["completed", "failed", "stopped"];
+var AgentRunsWsApi = class {
+  constructor(context, sendRequest, eventHandler) {
+    this.context = context;
+    this.sendRequest = sendRequest;
+    this.eventHandler = eventHandler;
+  }
+  call(type, payload) {
+    return this.sendRequest(payload, type, this.context);
+  }
+  /** Create a run, or get back the subject's live run. */
+  create(options) {
+    return this.call("agent_run_create" /* AgentRunCreate */, createRunBody(options));
+  }
+  /** Read a run (record + effective projection). */
+  get(runId) {
+    return this.call("agent_run_get" /* AgentRunGet */, { run_id: runId });
+  }
+  /**
+   * Every run about `subject` (a conversation, a document) you may see,
+   * newest first — the live run, if there is one, comes first.
+   */
+  bySubject(subject, limit = 20) {
+    return this.call("agent_run_by_subject" /* AgentRunBySubject */, { ...subjectOf(subject), limit });
+  }
+  /** The newest run of `subject`, or null. */
+  async latest(subject) {
+    const [first] = await this.bySubject(subject, 1);
+    return first ?? null;
+  }
+  /** Your runs in one status (default "running"). */
+  list(status = "running", limit = 50) {
+    return this.call("agent_run_list" /* AgentRunList */, { status, limit });
+  }
+  /** Durable events after `afterSeq`. */
+  events(runId, afterSeq = 0, limit = 500) {
+    return this.call("agent_run_events" /* AgentRunEvents */, { run_id: runId, after_seq: afterSeq, limit });
+  }
+  /** The children a run spawned, with their current status. */
+  children(runId) {
+    return this.call("agent_run_children" /* AgentRunChildren */, { run_id: runId });
+  }
+  /** Any control. Retrying with the same `controlId` is a no-op. */
+  control(runId, command, controlId = newControlId(command.command), capability) {
+    return this.call("agent_run_control" /* AgentRunControl */, { run_id: runId, control_id: controlId, command, capability });
+  }
+  stop(runId, reason, controlId) {
+    return this.control(runId, { command: "stop", reason }, controlId);
+  }
+  pause(runId, controlId) {
+    return this.control(runId, { command: "pause" }, controlId);
+  }
+  resume(runId, controlId) {
+    return this.control(runId, { command: "resume" }, controlId);
+  }
+  /** Queue input for the run's next safe boundary. */
+  steer(runId, input, controlId) {
+    return this.control(runId, { command: "steer", input }, controlId);
+  }
+  /** Decide an approval request; the digest ties it to one changeset. */
+  approve(runId, requestId, subjectDigest, reject, controlId) {
+    const decision = reject ? { decision: "reject", reason: reject.reason } : { decision: "approve" };
+    return this.control(runId, { command: "approve", request_id: requestId, decision, subject_digest: subjectDigest }, controlId);
+  }
+  /** Answer an input request. */
+  answer(runId, requestId, value, controlId) {
+    return this.control(runId, { command: "provide_input", request_id: requestId, value }, controlId);
+  }
+  /**
+   * Follow a run: replay after `afterSeq`, then live, until the run ends.
+   *
+   * Events that reach the socket before the subscription is known here are
+   * not lost: the durable log is read once the listener is in place, live
+   * events are held until that read is merged, and every seq is delivered
+   * exactly once, in order.
+   */
+  async subscribe(runId, options = {}) {
+    let last = options.afterSeq ?? 0;
+    let ready = false;
+    let closed = false;
+    const held = [];
+    const buffer = [];
+    const waiters = [];
+    let resolveDone;
+    const done = new Promise((r) => resolveDone = r);
+    const close = (ended) => {
+      if (closed) return;
+      closed = true;
+      if (ended) options.onEnd?.(last);
+      for (const w of waiters.splice(0)) w({ value: void 0, done: true });
+      resolveDone();
+    };
+    const deliver = (ev) => {
+      if (closed || ev.seq <= last) return;
+      last = ev.seq;
+      options.onEvent?.(ev);
+      const w = waiters.shift();
+      if (w) w({ value: ev, done: false });
+      else buffer.push(ev);
+    };
+    const listener = (message) => {
+      if (message.event_type === "agent_run_end") {
+        if (ready) close(true);
+        else held.push({ seq: Number.MAX_SAFE_INTEGER });
+        return;
+      }
+      const ev = message.payload;
+      if (ready) deliver(ev);
+      else held.push(ev);
+    };
+    const response = await this.call("agent_run_subscribe" /* AgentRunSubscribe */, {
+      run_id: runId,
+      after_seq: last
+    });
+    const subscriptionId = response.subscription_id;
+    this.eventHandler.addFlowEventListener(subscriptionId, listener);
+    const unsubscribe = async () => {
+      this.eventHandler.removeFlowEventListener(subscriptionId);
+      close(false);
+      await this.call("agent_run_unsubscribe" /* AgentRunUnsubscribe */, { subscription_id: subscriptionId }).catch(() => void 0);
+    };
+    options.signal?.addEventListener("abort", () => void unsubscribe(), { once: true });
+    for (; ; ) {
+      const page = await this.events(runId, last, 500);
+      page.forEach(deliver);
+      if (page.length < 500) break;
+    }
+    ready = true;
+    const endSeen = held.some((e) => e.seq === Number.MAX_SAFE_INTEGER);
+    held.filter((e) => e.seq !== Number.MAX_SAFE_INTEGER).sort((a, b) => a.seq - b.seq).forEach(deliver);
+    if (endSeen) close(true);
+    else {
+      const view = await this.get(runId).catch(() => null);
+      const finalized = !view?.run?.domain || view.run.domain.finalized !== false;
+      if (view && TERMINAL.includes(view.status) && finalized) {
+        const tail = await this.events(runId, last, 500).catch(() => []);
+        tail.forEach(deliver);
+        this.eventHandler.removeFlowEventListener(subscriptionId);
+        close(true);
+      }
+    }
+    void done.then(() => this.eventHandler.removeFlowEventListener(subscriptionId));
+    return {
+      get lastSeq() {
+        return last;
+      },
+      done,
+      unsubscribe,
+      [Symbol.asyncIterator]() {
+        return {
+          next: () => {
+            const ev = buffer.shift();
+            if (ev) return Promise.resolve({ value: ev, done: false });
+            if (closed) return Promise.resolve({ value: void 0, done: true });
+            return new Promise((r) => waiters.push(r));
+          },
+          return: async () => {
+            await unsubscribe();
+            return { value: void 0, done: true };
+          }
+        };
+      }
+    };
+  }
+};
+
 // src/functions-api.ts
 var FunctionsApi = class {
   constructor(repository, context, sendRequest) {
@@ -4062,7 +4493,8 @@ function normalizeHomePath(home) {
 // src/conversations.ts
 var DEFAULT_SEND_MESSAGE_INACTIVITY_TIMEOUT_MS = 12e4;
 var ConversationManager = class {
-  constructor(baseUrl, repository, authManager, options = {}, executeSql) {
+  constructor(baseUrl, repository, authManager, options = {}, executeSql, visitor) {
+    this.visitor = visitor;
     this.baseUrl = baseUrl.replace(/\/$/, "");
     this.repository = repository;
     this.authManager = authManager;
@@ -4183,6 +4615,45 @@ var ConversationManager = class {
       ]
     };
   }
+  /**
+   * Start (or resume) an ANONYMOUS conversation with an agent — a public
+   * website's chat, without login.
+   *
+   * Works on an anonymous connection only, and only with an agent that allows
+   * anonymous visitors (`anonymous.enabled: true` on its raisin:AIAgent). The
+   * server keeps the conversation in an ephemeral visitor session that only
+   * this browser session can read; the session secret is kept in
+   * sessionStorage (override with `options.store`), so a reload continues the
+   * same conversation. Then use `sendMessage`, `getMessages`, `subscribe` and
+   * `ConversationStore` / `useConversation` exactly as for a signed-in user.
+   *
+   * @example
+   * ```typescript
+   * const convo = await db.conversations.startAnonymous('/agents/website-assistant');
+   * for await (const ev of db.conversations.sendMessage(convo.conversationPath, 'Hello')) {
+   *   if (ev.type === 'text_chunk') append(ev.text);
+   *   if (ev.type === 'failed') showLimit(ev.code); // e.g. RATE_LIMITED, LIMIT_REACHED
+   * }
+   * ```
+   */
+  async startAnonymous(agent, options) {
+    if (!this.visitor) {
+      throw new Error("Anonymous chat needs a WebSocket database: use client.database(repo).");
+    }
+    return this.visitor.start(this.normalizeAgentPath(agent), options);
+  }
+  /** Forget the stored anonymous session for `agent` (the next start begins a new one). */
+  forgetAnonymous(agent, options) {
+    this.visitor?.forget(this.normalizeAgentPath(agent), options);
+  }
+  /** Whether this tab remembers an anonymous conversation with `agent`. */
+  hasStoredAnonymous(agent, options) {
+    return this.visitor?.remembers(this.normalizeAgentPath(agent), options) ?? false;
+  }
+  /** Whether `conversationPath` is an anonymous conversation of this client. */
+  isAnonymous(conversationPath) {
+    return this.visitor?.isAnonymous(conversationPath) ?? false;
+  }
   /**
    * Open an existing conversation by path.
    * Returns null if not found.
@@ -4228,6 +4699,7 @@ var ConversationManager = class {
    * Mark a conversation as read by setting unread_count to 0.
    */
   async markAsRead(conversationPath) {
+    if (this.isAnonymous(conversationPath)) return;
     const workspace = "raisin:access_control";
     await this.sqlQuery(
       `UPDATE '${workspace}' SET properties = jsonb_set(properties, '{unread_count}', '0'::jsonb) WHERE path = $1 AND node_type = 'raisin:Conversation'`,
@@ -4238,6 +4710,7 @@ var ConversationManager = class {
    * Mark a single message as read by the current user.
    */
   async markMessageAsRead(messagePath) {
+    if (messagePath.startsWith("/visitors/")) return;
     const workspace = "raisin:access_control";
     const now = (/* @__PURE__ */ new Date()).toISOString();
     await this.sqlQuery(
@@ -4262,6 +4735,18 @@ var ConversationManager = class {
    */
   async *sendMessage(conversationPath, content, options) {
     const shouldStream = options?.stream !== false;
+    if (this.visitor?.isAnonymous(conversationPath)) {
+      if (!shouldStream) {
+        await this.visitor.post(conversationPath, content);
+        yield { type: "waiting", timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+        return;
+      }
+      yield* this.visitor.stream(conversationPath, content, {
+        signal: options?.signal,
+        inactivityTimeoutMs: options?.inactivityTimeoutMs ?? DEFAULT_SEND_MESSAGE_INACTIVITY_TIMEOUT_MS
+      });
+      return;
+    }
     logger.debug("[ConversationManager] Starting SSE stream for message send");
     if (!shouldStream) {
       await this.createUserMessage(conversationPath, content);
@@ -4349,6 +4834,10 @@ var ConversationManager = class {
    */
   async createUserMessage(conversationPath, content) {
     logger.debug("[ConversationManager] Creating user message", { path: conversationPath });
+    if (this.visitor?.isAnonymous(conversationPath)) {
+      await this.visitor.post(conversationPath, content);
+      return;
+    }
     const workspace = "raisin:access_control";
     const properties = await this.loadConversationProperties(conversationPath, workspace);
     const flowInstanceId = typeof properties?.flow_instance_id === "string" ? properties.flow_instance_id.trim() : "";
@@ -4400,6 +4889,12 @@ var ConversationManager = class {
    * initiated messages, etc.). Auto-reconnects on disconnect.
    */
   subscribe(conversationPath, onEvent, options) {
+    if (this.visitor?.isAnonymous(conversationPath)) {
+      const stop = this.visitor.listen(conversationPath, onEvent);
+      options?.signal?.addEventListener("abort", stop, { once: true });
+      return { unsubscribe: stop, waitUntilConnected: async () => {
+      } };
+    }
     logger.info("[ConversationManager] Subscribing to SSE", { path: conversationPath });
     const sseUrl = `${this.baseUrl}/api/conversations/${this.repository}/events`;
     const headers = {};
@@ -4839,6 +5334,272 @@ var ConversationManager = class {
   }
 };
 
+// src/visitor-chat.ts
+function defaultVisitorSessionStore() {
+  const memory = /* @__PURE__ */ new Map();
+  const storage = () => {
+    try {
+      return typeof sessionStorage !== "undefined" ? sessionStorage : null;
+    } catch {
+      return null;
+    }
+  };
+  return {
+    get(key) {
+      try {
+        return storage()?.getItem(key) ?? memory.get(key) ?? null;
+      } catch {
+        return memory.get(key) ?? null;
+      }
+    },
+    set(key, value) {
+      memory.set(key, value);
+      try {
+        storage()?.setItem(key, value);
+      } catch {
+      }
+    },
+    remove(key) {
+      memory.delete(key);
+      try {
+        storage()?.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+var VisitorChatError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "VisitorChatError";
+    this.code = code;
+  }
+};
+var REBIND_CODES = /* @__PURE__ */ new Set(["NO_SESSION", "UNKNOWN_CONVERSATION"]);
+function asError(err) {
+  const e = err;
+  return new VisitorChatError(e?.message ?? String(err), e?.code ?? "UNAVAILABLE");
+}
+var VisitorChat = class {
+  constructor(repository, send, events, onReconnected) {
+    this.repository = repository;
+    this.send = send;
+    this.events = events;
+    this.byPath = /* @__PURE__ */ new Map();
+    this.token = null;
+    onReconnected?.(() => {
+      void this.rebindAll();
+    });
+  }
+  /** Whether `conversationPath` is a visitor conversation started here. */
+  isAnonymous(conversationPath) {
+    return this.byPath.has(conversationPath);
+  }
+  storeOf(options) {
+    if (options.store === false) return null;
+    return options.store ?? defaultVisitorSessionStore();
+  }
+  keyOf(agent, options) {
+    return options.storageKey ?? `raisindb:visitor:${this.repository}:${agent}`;
+  }
+  /** Start (or resume) a visitor conversation with `agent` (`/agents/<name>`). */
+  async start(agent, options = {}) {
+    const store = this.storeOf(options);
+    const key = this.keyOf(agent, options);
+    const sessionToken = options.sessionToken ?? this.token ?? store?.get(`${key}:session`) ?? void 0;
+    const conversationId = options.newConversation ? void 0 : options.conversationId ?? store?.get(`${key}:conversation`) ?? void 0;
+    let res;
+    try {
+      res = await this.send(
+        { agent, session_token: sessionToken, conversation_id: conversationId },
+        "visitor_chat_start"
+      );
+    } catch (err) {
+      const e = asError(err);
+      if ((conversationId || sessionToken) && !options.conversationId && !options.sessionToken && ["UNKNOWN_CONVERSATION", "INVALID_CONVERSATION", "SESSION_EXPIRED", "SESSION_MISMATCH"].includes(e.code)) {
+        store?.remove(`${key}:conversation`);
+        if (e.code !== "UNKNOWN_CONVERSATION" && e.code !== "INVALID_CONVERSATION") {
+          store?.remove(`${key}:session`);
+          this.token = null;
+        }
+        return this.start(agent, { ...options, newConversation: true });
+      }
+      throw e;
+    }
+    const token = res.session_token ?? sessionToken ?? this.token;
+    if (!token) throw new VisitorChatError("the server returned no session", "UNAVAILABLE");
+    this.token = token;
+    store?.set(`${key}:session`, token);
+    store?.set(`${key}:conversation`, res.conversation_id);
+    const path = res.conversation_path;
+    let entry = this.byPath.get(path);
+    if (!entry) {
+      entry = {
+        agent: res.agent,
+        conversationId: res.conversation_id,
+        subscriptionId: res.subscription_id,
+        listeners: /* @__PURE__ */ new Set(),
+        options
+      };
+      this.byPath.set(path, entry);
+    }
+    this.route(entry);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      id: res.conversation_id,
+      type: "ai_chat",
+      agentRef: res.agent,
+      conversationPath: path,
+      conversationWorkspace: res.conversation_workspace,
+      anonymous: true,
+      conversationId: res.conversation_id,
+      sessionToken: token,
+      limits: res.limits,
+      initialEvents: [{ type: "waiting", timestamp: now }]
+    };
+  }
+  /** Route the server's forwarded events for this conversation to its listeners. */
+  route(entry) {
+    this.events.removeFlowEventListener(entry.subscriptionId);
+    this.events.addFlowEventListener(entry.subscriptionId, (msg) => {
+      const event = msg.payload;
+      if (!event || typeof event.type !== "string") return;
+      for (const listener of entry.listeners) {
+        try {
+          listener(event);
+        } catch (err) {
+          logger.error("[VisitorChat] listener failed", err);
+        }
+      }
+    });
+  }
+  /** Re-prove the session on a new connection, for every conversation started here. */
+  async rebindAll() {
+    for (const entry of this.byPath.values()) {
+      try {
+        await this.send(
+          { agent: entry.agent, session_token: this.token, conversation_id: entry.conversationId },
+          "visitor_chat_start"
+        );
+        this.route(entry);
+      } catch (err) {
+        logger.warn("[VisitorChat] could not resume a conversation after reconnect", err);
+      }
+    }
+  }
+  /** Listen to a visitor conversation's events. Returns an unsubscribe function. */
+  listen(conversationPath, listener) {
+    const entry = this.require(conversationPath);
+    entry.listeners.add(listener);
+    return () => {
+      entry.listeners.delete(listener);
+    };
+  }
+  require(conversationPath) {
+    const entry = this.byPath.get(conversationPath);
+    if (!entry) {
+      throw new VisitorChatError(
+        "not a visitor conversation of this client; call startAnonymous first",
+        "UNKNOWN_CONVERSATION"
+      );
+    }
+    return entry;
+  }
+  /** Make sure this connection is bound (after a reconnect nothing else may read the home). */
+  async ensureBound(conversationPath) {
+    const entry = this.require(conversationPath);
+    await this.send(
+      { agent: entry.agent, session_token: this.token, conversation_id: entry.conversationId },
+      "visitor_chat_start"
+    ).catch((err) => {
+      throw asError(err);
+    });
+  }
+  /** Send one visitor message. Events arrive through {@link listen}. */
+  async post(conversationPath, text) {
+    const entry = this.require(conversationPath);
+    const once = async () => await this.send(
+      { conversation_id: entry.conversationId, text },
+      "visitor_chat_send"
+    );
+    try {
+      const res = await once();
+      return { messageId: res.message_id, messagesLeft: res.messages_left };
+    } catch (err) {
+      const e = asError(err);
+      if (!REBIND_CODES.has(e.code)) throw e;
+      await this.ensureBound(conversationPath);
+      this.route(entry);
+      const res = await once().catch((again) => {
+        throw asError(again);
+      });
+      return { messageId: res.message_id, messagesLeft: res.messages_left };
+    }
+  }
+  /**
+   * Send one visitor message and stream the turn: `text_chunk`,
+   * `tool_call_started`, `tool_call_completed`, … until `done`. A refusal
+   * ends the stream with `failed` (its `code` says why). No event for
+   * `inactivityTimeoutMs` ends it with a synthetic `waiting`.
+   */
+  async *stream(conversationPath, text, options = {}) {
+    const queue = [];
+    let wake = null;
+    const push = (event) => {
+      queue.push(event);
+      wake?.();
+    };
+    const stop = this.listen(conversationPath, push);
+    const onAbort = () => push({ type: "failed", error: "aborted", code: "ABORTED", timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    const timeout = options.inactivityTimeoutMs ?? 12e4;
+    try {
+      try {
+        await this.post(conversationPath, text);
+      } catch (err) {
+        const e = asError(err);
+        yield { type: "failed", error: e.message, code: e.code, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+        return;
+      }
+      for (; ; ) {
+        if (!queue.length) {
+          const idle = await new Promise((resolve) => {
+            const timer = timeout > 0 ? setTimeout(() => resolve(true), timeout) : null;
+            wake = () => {
+              if (timer) clearTimeout(timer);
+              resolve(false);
+            };
+          });
+          wake = null;
+          if (idle && !queue.length) {
+            yield { type: "waiting", timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+            return;
+          }
+        }
+        const event = queue.shift();
+        yield event;
+        if (event.type === "done" || event.type === "failed" || event.type === "waiting") return;
+      }
+    } finally {
+      stop();
+      options.signal?.removeEventListener("abort", onAbort);
+    }
+  }
+  /** Whether the store remembers a conversation with `agent`. */
+  remembers(agent, options = {}) {
+    const store = this.storeOf(options);
+    return !!store?.get(`${this.keyOf(agent, options)}:conversation`);
+  }
+  /** Forget the stored session (e.g. a "new chat" button that should start a new session). */
+  forget(agent, options = {}) {
+    const store = this.storeOf(options);
+    const key = this.keyOf(agent, options);
+    store?.remove(`${key}:session`);
+    store?.remove(`${key}:conversation`);
+    this.token = null;
+  }
+};
+
 // src/flow-client.ts
 var FlowClient = class _FlowClient {
   /**
@@ -5615,6 +6376,16 @@ var Database = class _Database {
     }
     return this._flowsApi;
   }
+  /**
+   * Durable agent runs over this WebSocket connection: find a subject's run,
+   * follow it live (gap-free, resumable), control it, list its children.
+   */
+  runs() {
+    if (!this._runsApi) {
+      this._runsApi = new AgentRunsWsApi(this._context, this.sendRequest, this.eventHandler);
+    }
+    return this._runsApi;
+  }
   /**
    * Get FunctionsApi for invoking server-side functions via WebSocket
    */
@@ -5721,7 +6492,13 @@ var Database = class _Database {
         this.repository,
         this.httpOptions.authManager,
         {},
-        (query, params) => this.executeSql(query, params)
+        (query, params) => this.executeSql(query, params),
+        new VisitorChat(
+          this.repository,
+          (payload, requestType) => this.sendRequest(payload, requestType),
+          this.eventHandler,
+          this.httpOptions.onReconnected
+        )
       );
     }
     return this._conversationManager;
@@ -7351,6 +8128,82 @@ function readTokensFromFragment(hashOrUrl) {
   return { accessToken, refreshToken: params.get("refresh_token") };
 }
 
+// src/node-dev.ts
+var NodeDevApi = class {
+  constructor(repository, transport) {
+    this.repository = repository;
+    this.transport = transport;
+  }
+  /** Call any method by name (the typed helpers below all use this). */
+  call(method, request) {
+    const branch = typeof request.branch === "string" ? `?branch=${encodeURIComponent(request.branch)}` : "";
+    return this.transport.request(
+      "POST",
+      `/api/node-dev/${encodeURIComponent(this.repository)}/${method}${branch}`,
+      request
+    );
+  }
+  changeset(o) {
+    const { idempotencyKey, ...rest } = o;
+    return { ...rest, idempotency_key: idempotencyKey };
+  }
+  stat(target, o = {}) {
+    return this.call("stat", { ...o, target });
+  }
+  read(target, o = {}) {
+    return this.call("read", { ...o, target });
+  }
+  list(target, o = {}) {
+    return this.call("list", { ...o, target });
+  }
+  diff(target, from, to, o = {}) {
+    return this.call("diff", { ...o, target, from, to });
+  }
+  /** Changes inside the roots after `since` (a cursor from a previous call). */
+  watch(since, o = {}) {
+    return this.call("watch", { ...o, since });
+  }
+  dryRun(o) {
+    return this.call("dry_run", this.changeset(o));
+  }
+  propose(o) {
+    return this.call(
+      "propose",
+      this.changeset(o)
+    );
+  }
+  getChangeset(changesetId, o = {}) {
+    return this.call("get_changeset", { ...o, changeset_id: changesetId });
+  }
+  listChangesets(o = {}) {
+    return this.call("list_changesets", { ...o });
+  }
+  /** Commit; pass the reviewed digest to bind the commit to that approval. */
+  commit(changesetId, expectedDigest, o = {}) {
+    return this.call("commit", { ...o, changeset_id: changesetId, expected_digest: expectedDigest });
+  }
+  discard(changesetId, o = {}) {
+    return this.call("discard", { ...o, changeset_id: changesetId });
+  }
+  /** Propose and commit in one call. */
+  apply(o) {
+    return this.call("apply", this.changeset(o));
+  }
+  forkBranch(name, o = {}) {
+    return this.call("fork_branch", { ...o, name });
+  }
+  diffBranch(base = "main", o = {}) {
+    return this.call("diff_branch", { ...o, base });
+  }
+  mergeBranch(target, o = {}) {
+    const { dryRun, ...rest } = o;
+    return this.call("merge_branch", { ...rest, target, dry_run: dryRun });
+  }
+  discardBranch(o = {}) {
+    return this.call("discard_branch", { ...o });
+  }
+};
+
 // src/http-client.ts
 var RaisinHttpClient = class extends import_events3.EventEmitter {
   constructor(baseUrl, options = {}) {
@@ -8076,6 +8929,33 @@ var RaisinHttpClient = class extends import_events3.EventEmitter {
    * @param input - Input data passed to the function
    * @returns Execution ID and job ID for tracking
    */
+  /**
+   * Durable agent runs of `repository`: create, read, control, stream, and
+   * drive them directly (see {@link AgentRunsApi}).
+   */
+  agentRuns(repository) {
+    return new AgentRunsApi(repository, {
+      request: async (method, path, body) => (await this.request({ method, path, body })).data,
+      url: (path) => `${this.baseUrl}${path}`,
+      headers: () => {
+        const token = this.authManager.getAccessToken();
+        const headers = {};
+        if (token) headers["Authorization"] = `Bearer ${token}`;
+        return headers;
+      },
+      fetch: this.fetchImpl
+    });
+  }
+  /**
+   * The node-development surface of `repository`: typed reads, atomic
+   * changesets with review and idempotency, branch worktrees (see
+   * {@link NodeDevApi}).
+   */
+  nodeDev(repository) {
+    return new NodeDevApi(repository, {
+      request: async (method, path, body) => (await this.request({ method, path, body })).data
+    });
+  }
   async invokeFunction(repository, functionName, input, options) {
     const requestTimeoutMs = options?.requestTimeoutMs ?? this.options.requestTimeout;
     let waitTimeoutMs = options?.waitTimeoutMs;
@@ -8279,6 +9159,14 @@ var HttpDatabase = class _HttpDatabase {
   /**
    * Get FunctionsApi for invoking server-side functions via HTTP
    */
+  /** Durable agent runs of this repository. */
+  agentRuns() {
+    return this.client.agentRuns(this.repository);
+  }
+  /** The node-development surface of this repository. */
+  nodeDev() {
+    return this.client.nodeDev(this.repository);
+  }
   functions() {
     return new HttpFunctionsApi(
       this.repository,
@@ -9477,7 +10365,11 @@ var _RaisinClient = class _RaisinClient extends import_events4.EventEmitter {
       void 0,
       () => this.getUploadManager(),
       (options) => this.signAssetUrl(options),
-      { httpBaseUrl: this._httpBaseUrl, authManager: this.authManager }
+      {
+        httpBaseUrl: this._httpBaseUrl,
+        authManager: this.authManager,
+        onReconnected: (callback) => this.onReconnected(callback)
+      }
     );
   }
   /**
@@ -10857,6 +11749,34 @@ var ConversationStore = class {
     this._watchdogIntervalMs = options.watchdogIntervalMs ?? 3e4;
     if (this._conversationPath) {
       this.ensureSubscription();
+    } else if (this.createOptions?.anonymous) {
+      void this.resumeAnonymous();
+    }
+  }
+  anonymousOptions() {
+    const a = this.createOptions?.anonymous;
+    if (!a) return null;
+    return a === true ? {} : a;
+  }
+  /**
+   * Resume the visitor conversation this tab already has (the session secret
+   * and conversation id live in sessionStorage), and load its history. A tab
+   * without one starts nothing until the first message.
+   */
+  async resumeAnonymous() {
+    const opts = this.anonymousOptions();
+    if (!opts || !this.createOptions || this._conversationPath) return;
+    const agent = this.createOptions.participant;
+    try {
+      if (!this.manager.hasStoredAnonymous(agent, opts)) return;
+      const convo = await this.manager.startAnonymous(agent, opts);
+      if (this._conversationPath) return;
+      this._conversationPath = convo.conversationPath;
+      this._conversationType = convo.type;
+      this.ensureSubscription();
+      await this.loadMessages();
+    } catch (err) {
+      logger.debug("[ConversationStore] No visitor conversation to resume", err);
     }
   }
   // ==========================================================================
@@ -10911,7 +11831,8 @@ var ConversationStore = class {
         throw new Error("No conversationPath and no createOptions provided");
       }
       try {
-        const convo = await this.manager.create({
+        const anonymous = this.anonymousOptions();
+        const convo = anonymous ? await this.manager.startAnonymous(this.createOptions.participant, anonymous) : await this.manager.create({
           participant: this.createOptions.participant,
           input: this.createOptions.input
         });
@@ -12727,6 +13648,8 @@ function createRaisinVue(vue) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AgentRunsApi,
+  AgentRunsWsApi,
   AllNodeEventTypes,
   Archetypes,
   AuthManager,
@@ -12767,6 +13690,7 @@ function createRaisinVue(vue) {
   McpClient,
   MemoryTokenStorage,
   NodeBuilder,
+  NodeDevApi,
   NodeEventType,
   NodeFileSource,
   NodeHelpers,
@@ -12796,6 +13720,7 @@ function createRaisinVue(vue) {
   UploadErrorCode,
   UploadManager,
   Uploader,
+  VisitorChatError,
   WorkspaceClient,
   WorkspaceManager,
   calculateChunkCount,
@@ -12817,6 +13742,7 @@ function createRaisinVue(vue) {
   createSqlHandler,
   createSubscriptionAdapter,
   decodeMessage,
+  defaultVisitorSessionStore,
   encodeMessage,
   getChunkRange,
   getContentType,
@@ -12834,12 +13760,14 @@ function createRaisinVue(vue) {
   isTerminalEvent,
   isWebSocketClient,
   logger,
+  newControlId,
   normalizeHomePath,
   projectPlansFromMessages,
   readTokensFromFragment,
   rowsToObjects,
   setLogLevel,
   sleep,
+  subjectOf,
   useConversation,
   useConversationList,
   useFlow,