@securecoms/agent-runtime 0.9.2 → 0.9.4

package/README.md

@@ -286,7 +286,7 @@ to a host the operator did not name.
 | `fetch_url` | `url` | Fetches a page and returns extracted text (HTML is stripped to text). Up to 3 redirects, 10 s timeout, 2 MB response cap. |
 | `web_search` | `query`, `count` (1–10, default 5) | `requires: [search_provider]` — needs a readable, non-empty `SECURECOMS_BRAVE_KEY_FILE` or `SECURECOMS_TAVILY_KEY_FILE`; Brave is used first when both are set. |
 | `http_request` | `name` (a configured `endpoint:<name>`), `path` (a query string is kept, a `#fragment` is dropped), `method` (GET/POST/PUT/DELETE), `body` | `requires: [any_endpoint]`. The model names an endpoint and a path, never a host; a path that would leave the endpoint's `baseUrl` origin is refused. |
-| `sql_query` | `name` (a configured `database:<name>`), `sql` (read-only `SELECT` only; a `;` or a write keyword anywhere in the text — inside a string literal or a comment included — is refused) | `requires: [any_database]`. SQLite or Postgres (`pg` required separately for Postgres). Results capped at 200 rows. |
+| `sql_query` | `name` (a configured `database:<name>`), `sql` (read-only `SELECT` only; a `;` or a write keyword anywhere in the text — inside a string literal or a comment included — is refused) | `requires: [any_database]`. SQLite or Postgres (`pg` required separately for Postgres). Results capped at 200 rows. Postgres values come back as the server's text (json/jsonb as a JSON string, arrays like `{1,2}`, timestamps, int8 and numeric as strings); rows past a 1 MiB value budget are dropped, and `truncated_reason` (`row_limit` or `size_limit`) says why rows are missing. |
 
 ## skills.json
 

package/dist/bin.js

@@ -2449,6 +2449,7 @@ var httpRequest = async (args, ctx) => {
 // src/builtins/sql-query.ts
 import { readFileSync as readFileSync5 } from "node:fs";
 import { spawn } from "node:child_process";
+import { createConnection } from "node:net";
 
 // src/sql-guard.ts
 var SqlNotReadOnlyError = class extends Error {
@@ -2641,15 +2642,181 @@ function executeSqliteQuery(path, sql, options = {}) {
     }));
   });
 }
-function envelope(columns, rows, truncated) {
+var PG_WIRE_BYTE_CAP = 4 * 1024 * 1024;
+var PG_ROW_BYTE_BUDGET = SQLITE_IPC_CAP_BYTES;
+var PG_IDLE_IN_TRANSACTION_MS = 15e3;
+var PG_CURSOR = "sc_q";
+var PG_SCALAR_PARSERS = {
+  16: (t) => t === "t",
+  // bool
+  21: Number,
+  // int2
+  23: Number,
+  // int4
+  26: Number,
+  // oid
+  700: Number,
+  // float4
+  701: Number
+  // float8
+};
+var PG_TEXT_TYPES = {
+  getTypeParser(oid, format) {
+    if (format === "binary") return (value) => value;
+    return PG_SCALAR_PARSERS[oid] ?? ((value) => value);
+  }
+};
+var PgWireByteCapError = class extends Error {
+  constructor() {
+    super("database result exceeded the size limit");
+    this.name = "PgWireByteCapError";
+  }
+};
+var PgWireBoundUnavailableError = class extends Error {
+  constructor() {
+    super(
+      'the installed "pg" driver does not expose its socket, so the result size cannot be bounded; the query was not run'
+    );
+    this.name = "PgWireBoundUnavailableError";
+  }
+};
+var PgDriverMissingError = class extends Error {
+};
+function isPgStream(value) {
+  return typeof value === "object" && value !== null && typeof value.on === "function" && typeof value.destroy === "function";
+}
+async function loadInstalledPg() {
+  return import("pg");
+}
+function rowValueBytes(row) {
+  let n = 0;
+  for (const v of row) n += typeof v === "string" ? Buffer.byteLength(v) : 8;
+  return n;
+}
+function sendCancelRequest(client) {
+  const { processID, secretKey, host, port } = client;
+  if (typeof processID !== "number" || typeof secretKey !== "number") return;
+  if (typeof host !== "string" || typeof port !== "number") return;
+  const packet = Buffer.alloc(16);
+  packet.writeInt32BE(16, 0);
+  packet.writeInt32BE(80877102, 4);
+  packet.writeInt32BE(processID, 8);
+  packet.writeInt32BE(secretKey, 12);
+  const socket = host.startsWith("/") ? createConnection(`${host}/.s.PGSQL.${port}`) : createConnection(port, host);
+  socket.setTimeout(PG_CANCEL_TIMEOUT_MS, () => socket.destroy());
+  socket.on("error", () => socket.destroy());
+  socket.once("connect", () => socket.end(packet));
+  socket.unref();
+}
+var PG_CANCEL_TIMEOUT_MS = 5e3;
+async function executePostgresQuery(connectionString, sql, options = {}) {
+  const timeoutMs = Math.max(1, Math.floor(options.timeoutMs ?? SQL_TIMEOUT_MS));
+  const wireByteCap = options.wireByteCap ?? PG_WIRE_BYTE_CAP;
+  if (options.signal?.aborted) throw new Error("Postgres query cancelled");
+  let pg;
+  try {
+    pg = await (options.loadDriver ?? loadInstalledPg)();
+  } catch {
+    throw new PgDriverMissingError('the optional "pg" module is not installed (npm i -g pg)');
+  }
+  const Client = pg.Client ?? pg.default?.Client;
+  if (!Client) throw new Error(`the installed "pg" module does not export a Client`);
+  const client = new Client({
+    connectionString,
+    // never logged (D4)
+    statement_timeout: timeoutMs,
+    connectionTimeoutMillis: timeoutMs,
+    types: PG_TEXT_TYPES
+  });
+  client.on("error", () => {
+  });
+  let stopped;
+  const stop = (reason) => {
+    if (stopped) return;
+    stopped = reason;
+    sendCancelRequest(client);
+    const stream = client.connection?.stream;
+    if (isPgStream(stream)) stream.destroy();
+    else void client.end().catch(() => {
+    });
+  };
+  const onAbort = () => stop("cancelled");
+  const deadline = setTimeout(() => stop("deadline"), timeoutMs);
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  const stoppedError = () => {
+    if (stopped === "capped") return new PgWireByteCapError();
+    if (stopped === "deadline") return new Error(`Postgres query timed out after ${timeoutMs}ms`);
+    if (stopped === "cancelled") return new Error("Postgres query cancelled");
+    return void 0;
+  };
+  let began = false;
+  try {
+    try {
+      await client.connect();
+    } catch (error) {
+      throw stoppedError() ?? error;
+    }
+    const early = stoppedError();
+    if (early) throw early;
+    const stream = client.connection?.stream;
+    if (!isPgStream(stream)) throw new PgWireBoundUnavailableError();
+    let wireBytes = 0;
+    stream.on("data", (chunk) => {
+      if (stopped) return;
+      wireBytes += typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.byteLength;
+      if (wireBytes > wireByteCap) stop("capped");
+    });
+    const run = async (text, rowMode) => {
+      try {
+        const result = await client.query(rowMode ? { text, rowMode } : text);
+        const late = stoppedError();
+        if (late) throw late;
+        return result;
+      } catch (error) {
+        throw stoppedError() ?? error;
+      }
+    };
+    began = true;
+    await run("BEGIN READ ONLY");
+    await run(`SET LOCAL statement_timeout = ${timeoutMs}`);
+    await run(`SET LOCAL idle_in_transaction_session_timeout = ${Math.max(timeoutMs, PG_IDLE_IN_TRANSACTION_MS)}`);
+    await run(`DECLARE ${PG_CURSOR} NO SCROLL CURSOR FOR ${sql}`);
+    const fetched = await run(`FETCH FORWARD ${SQL_ROW_CAP + 1} FROM ${PG_CURSOR}`, "array");
+    const columns = fetched.fields.map((f) => f.name);
+    const all = fetched.rows;
+    let truncatedReason = all.length > SQL_ROW_CAP ? "row_limit" : void 0;
+    const rows = [];
+    let bytes = 0;
+    for (const row of all.slice(0, SQL_ROW_CAP)) {
+      bytes += rowValueBytes(row);
+      if (bytes > PG_ROW_BYTE_BUDGET) {
+        truncatedReason = "size_limit";
+        break;
+      }
+      rows.push(row);
+    }
+    return { columns, rows, truncated: truncatedReason !== void 0, truncatedReason };
+  } finally {
+    options.signal?.removeEventListener("abort", onAbort);
+    if (began && !stopped) await client.query("ROLLBACK").catch(() => {
+    });
+    if (stopped) void client.end().catch(() => {
+    });
+    else await client.end().catch(() => {
+    });
+    clearTimeout(deadline);
+  }
+}
+function envelope(columns, rows, truncated, reason) {
   let kept = rows;
-  let cut = truncated;
+  let why = truncated ? reason ?? "row_limit" : void 0;
+  const render = () => JSON.stringify(why ? { columns, rows: kept, truncated: true, truncated_reason: why } : { columns, rows: kept, truncated: false });
   try {
-    let out = JSON.stringify({ columns, rows: kept, truncated: cut });
+    let out = render();
     while (resultBytes(out) > RESULT_CAP && kept.length > 0) {
       kept = kept.slice(0, Math.floor(kept.length / 2));
-      cut = true;
-      out = JSON.stringify({ columns, rows: kept, truncated: cut });
+      why = "size_limit";
+      out = render();
     }
     if (resultBytes(out) <= RESULT_CAP) return out;
   } catch {
@@ -2674,46 +2841,21 @@ var sqlQuery = async (args, ctx) => {
   try {
     if ("sqlite" in db) {
       const result = await executeSqliteQuery(db.sqlite, sql, { signal: ctx.signal });
-      return envelope(result.columns, result.rows, result.truncated);
+      return envelope(result.columns, result.rows, result.truncated, result.truncatedReason);
     }
-    let pg;
     try {
-      pg = await import("pg");
-    } catch {
-      return toolError(`database "${name}" is Postgres, but the optional "pg" module is not installed (npm i -g pg)`);
-    }
-    const Client = pg.Client ?? pg.default?.Client;
-    if (!Client) return toolError(`the installed "pg" module does not export a Client`);
-    const client = new Client({
-      connectionString: readFileSync5(db.postgresUrlFile, "utf8").trim(),
-      // never logged (D4)
-      statement_timeout: SQL_TIMEOUT_MS,
-      connectionTimeoutMillis: SQL_TIMEOUT_MS,
-      query_timeout: SQL_TIMEOUT_MS
-    });
-    let cancelled = ctx.signal?.aborted ?? false;
-    const cancel = () => {
-      cancelled = true;
-      void client.end().catch(() => {
-      });
-    };
-    if (cancelled) throw new Error("Postgres query cancelled");
-    ctx.signal?.addEventListener("abort", cancel, { once: true });
-    try {
-      await client.connect();
-      if (cancelled) throw new Error("Postgres query cancelled");
-      await client.query("BEGIN; SET TRANSACTION READ ONLY;");
-      const res = await client.query({ text: sql, rowMode: "array" });
-      if (cancelled) throw new Error("Postgres query cancelled");
-      const columns = res.fields.map((f) => f.name);
-      const rows = res.rows.slice(0, SQL_ROW_CAP);
-      return envelope(columns, rows, res.rows.length > SQL_ROW_CAP);
-    } finally {
-      ctx.signal?.removeEventListener("abort", cancel);
-      if (!cancelled) await client.query("ROLLBACK").catch(() => {
-      });
-      await client.end().catch(() => {
-      });
+      const result = await executePostgresQuery(
+        readFileSync5(db.postgresUrlFile, "utf8").trim(),
+        // never logged (D4)
+        sql,
+        { signal: ctx.signal }
+      );
+      return envelope(result.columns, result.rows, result.truncated, result.truncatedReason);
+    } catch (e) {
+      if (e instanceof PgDriverMissingError) {
+        return toolError(`database "${name}" is Postgres, but ${e.message}`);
+      }
+      throw e;
     }
   } catch (e) {
     return toolError(e instanceof Error ? e.message : String(e));
@@ -3340,6 +3482,49 @@ import { readFileSync as readFileSync7 } from "node:fs";
 import { WebSocket } from "node:http";
 import { homedir as homedir3 } from "node:os";
 import { join as join5 } from "node:path";
+
+// src/status-reporter.ts
+function createStatusReporter(log, fetchImpl = fetch) {
+  const channels = /* @__PURE__ */ new Map();
+  async function post(endpoint, channelId, state) {
+    try {
+      const res = await fetchImpl(`${endpoint.httpBase}/v1/status`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${endpoint.token}` },
+        body: JSON.stringify({ channel_id: channelId, state })
+      });
+      if (!res.ok) log("warn", "transport.status_failed", { state: logLabel(state), http_status: res.status });
+      await res.body?.cancel();
+    } catch (e) {
+      log("warn", "transport.status_failed", { state: logLabel(state) }, e);
+    }
+  }
+  async function drain(channelId, entry) {
+    while (entry.desired !== entry.sent) {
+      const state = entry.desired;
+      entry.sent = state;
+      await post(entry.endpoint, channelId, state);
+    }
+    entry.inFlight = false;
+    if (channels.get(channelId) === entry) channels.delete(channelId);
+  }
+  return {
+    set(endpoint, channelId, state) {
+      let entry = channels.get(channelId);
+      if (!entry) {
+        entry = { desired: state, endpoint, sent: null, inFlight: false };
+        channels.set(channelId, entry);
+      }
+      entry.desired = state;
+      entry.endpoint = endpoint;
+      if (entry.inFlight) return;
+      entry.inFlight = true;
+      void drain(channelId, entry);
+    }
+  };
+}
+
+// src/data-plane.ts
 var NO_TURN_MEMORY = Object.freeze({
   recent: Object.freeze([]),
   facts: Object.freeze([])
@@ -3408,6 +3593,12 @@ function parseTurnAuthorization(value) {
     tool_grants: Object.freeze(grants)
   });
 }
+var VOICE_GUIDANCE_MAX_CHARS = 1e3;
+function parseVoiceGuidance(frame) {
+  if (frame.voice !== true || typeof frame.guidance !== "string") return void 0;
+  const g = frame.guidance.trim().slice(0, VOICE_GUIDANCE_MAX_CHARS);
+  return g || void 0;
+}
 var SEEN_MAX = 5e3;
 var PENDING_REPLY_MAX = 1e3;
 var TERMINAL_REPLY_ERRORS = /* @__PURE__ */ new Set(["agent_paused", "send_forbidden"]);
@@ -3473,6 +3664,8 @@ var SecureComsDataPlane = class {
   seq = 0;
   /** in_reply_to → timing of a reply handed to the daemon, until its `sent` frame. */
   pendingReplies = /* @__PURE__ */ new Map();
+  /** #910: working/idle for the web "thinking" strip; fire-and-forget, per-channel ordered. */
+  status;
   constructor(cfg, onMessage) {
     this.identityId = cfg.identityId;
     const dir = cfg.connectionsDir ?? join5(homedir3(), ".securecoms", "connections");
@@ -3492,6 +3685,7 @@ var SecureComsDataPlane = class {
     this.onMessage = onMessage;
     this.noticeReplies = cfg.noticeReplies ?? /* @__PURE__ */ new Set();
     this.clock = cfg.clock ?? (() => performance.now());
+    this.status = createStatusReporter(this.log);
   }
   elapsed(from, to = this.clock()) {
     return Math.max(0, Math.round(to - from));
@@ -3759,6 +3953,7 @@ var SecureComsDataPlane = class {
     let handlerMs = 0;
     let sendMs = 0;
     let outcome = "failed";
+    let reportedWorking = false;
     try {
       if (!this.seen.has(messageId)) {
         const receiptStart = this.clock();
@@ -3785,26 +3980,33 @@ var SecureComsDataPlane = class {
           this.turns.set(ws, socketTurns);
         }
         socketTurns.add(turnController);
+        const text = String(frame.text ?? "");
+        if (text.trim()) {
+          reportedWorking = true;
+          this.status.set({ httpBase, token }, channelId, "working");
+        }
         const handlerStart = this.clock();
+        const voiceGuidance = parseVoiceGuidance(frame);
         const reply = await this.onMessage({
-          text: String(frame.text ?? ""),
+          text,
           senderId: String(frame.sender_id ?? ""),
           channelId,
           messageId,
           authorization: parseTurnAuthorization(frame.authorization),
           memory: parseTurnMemory(frame.memory),
-          seq: arrival.seq
+          seq: arrival.seq,
+          ...voiceGuidance ? { voiceGuidance } : {}
         }, turnController.signal);
         handlerMs = this.elapsed(handlerStart);
         if (reply != null) {
-          const text = String(reply);
+          const text2 = String(reply);
           const sendStart = this.clock();
           ws.send(JSON.stringify({
             type: "send",
             channel_id: channelId,
-            text,
+            text: text2,
             in_reply_to: messageId,
-            ...this.noticeReplies.has(text) ? { notice: true } : {}
+            ...this.noticeReplies.has(text2) ? { notice: true } : {}
           }));
           const sentAt = this.clock();
           sendMs = this.elapsed(sendStart, sentAt);
@@ -3823,6 +4025,7 @@ var SecureComsDataPlane = class {
       this.log("error", "transport.handler_failed", {}, e);
       this.failTurn(ws, messageId, "turn_failed");
     } finally {
+      if (reportedWorking) this.status.set({ httpBase, token }, channelId, "idle");
       if (turnController) {
         const socketTurns = this.turns.get(ws);
         socketTurns?.delete(turnController);
@@ -3892,6 +4095,7 @@ async function runToolCalls(toolCalls, skills, context) {
 }
 
 // src/turn-loop.ts
+var VOICE_TURN_PREFIX = "This message was spoken on a live voice call and your reply will be read aloud: plain spoken sentences, no markdown, lists, links or code. Use your tools as usual when the question needs them. ";
 var DEFAULT_SYSTEM_PROMPT = "You are a SecureComs agent working inside a private, end-to-end encrypted messaging enclave for one business; the people you talk to are its staff, partners and customers. Answer questions in the chat, and keep replies to the length the question needs.";
 var DEFAULT_MAX_ITERATIONS = 5;
 var DEFAULT_MAX_CONCURRENT_TURNS = 4;
@@ -4313,7 +4517,12 @@ function buildHandler(deps) {
     const memory = memoryFor(m.channelId);
     memory.replace(m.memory);
     const promptStart = clock();
-    const system = { role: "system", content: deps.systemPromptFor() };
+    const system = {
+      role: "system",
+      content: m.voiceGuidance ? `${deps.systemPromptFor()}
+
+${VOICE_TURN_PREFIX}${m.voiceGuidance}` : deps.systemPromptFor()
+    };
     const recallStart = clock();
     const recalledText = await memory.recall(text);
     live();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securecoms/agent-runtime",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "type": "module",
   "bin": {
     "securecoms-agent": "dist/bin.js"
@@ -32,7 +32,7 @@
   },
   "dependencies": {},
   "peerDependencies": {
-    "pg": ">=8"
+    "pg": ">=8.11 <9"
   },
   "peerDependenciesMeta": {
     "pg": {
@@ -42,6 +42,7 @@
   "devDependencies": {
     "@types/ws": "^8.5.12",
     "esbuild": "0.24.0",
+    "pg": "~8.23.0",
     "typescript": "^5.4.0",
     "vitest": "^3.2.6",
     "ws": "^8.21.0"

package/skills/sql_query/SKILL.md

@@ -18,4 +18,10 @@ database the operator configured; never invent a connection string. A semicolon
 or a write keyword inside a string literal or a comment is also refused, so
 rewrite such a value out of the query (a bound-looking literal like '--' or
 'DROP' will not pass). If a query is refused, rewrite it as a SELECT rather than
-retrying the same statement.
+retrying the same statement. Values come back as the database's text: a
+Postgres json or jsonb value is a JSON string, arrays look like {1,2}, and
+timestamps, int8 and numeric are strings. When `truncated` is true,
+`truncated_reason` says why: `row_limit` means more rows exist than were
+returned, and `size_limit` means rows were dropped because they were too large
+(a single row over 1 MiB comes back as no rows with `size_limit`, not as an
+empty result). Select fewer or narrower columns rather than retrying as is.