@raisindb/client 0.5.7 → 0.5.9

package/dist/index.mjs

@@ -491,6 +491,15 @@ 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";
@@ -2975,6 +2984,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) {
@@ -4280,6 +4700,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
    */
@@ -6016,6 +6446,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 EventEmitter {
   constructor(baseUrl, options = {}) {
@@ -6741,6 +7247,33 @@ var RaisinHttpClient = class extends 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;
@@ -6944,6 +7477,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,
@@ -9327,6 +9868,8 @@ function isFlowDefinitionContainer(node) {
   return node.node_type === "raisin:FlowContainer";
 }
 export {
+  AgentRunsApi,
+  AgentRunsWsApi,
   AllNodeEventTypes,
   Archetypes,
   AuthManager,
@@ -9367,6 +9910,7 @@ export {
   McpClient,
   MemoryTokenStorage,
   NodeBuilder,
+  NodeDevApi,
   NodeEventType,
   NodeFileSource,
   NodeHelpers,
@@ -9434,12 +9978,14 @@ export {
   isTerminalEvent,
   isWebSocketClient,
   logger,
+  newControlId,
   normalizeHomePath,
   projectPlansFromMessages,
   readTokensFromFragment,
   rowsToObjects,
   setLogLevel,
   sleep,
+  subjectOf,
   useConversation,
   useConversationList,
   useFlow,