@gaunt-sloth/core 2.0.0-alpha.8 → 2.0.0-beta.0

package/dist/utils/untrustedText.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @module utils/untrustedText
+ *
+ * **The structural delimiters gsloth wraps untrusted text in, and the one function that neutralizes
+ * a forged one.**
+ *
+ * Text that arrived from outside this process — an MCP server's discovery `instructions`, a command
+ * string the model composed from an issue body or a fetched page — is quoted into the model's
+ * context in several places. Wherever it is, the same two things have to be true:
+ *
+ * 1. the quoted text is visibly fenced, so the model can tell data from first-party instruction; and
+ * 2. **the quoted text cannot forge the fence** and escape it.
+ *
+ * (2) is the load-bearing half, and it is why the delimiters and the defang live together in one
+ * module rather than beside each consumer. A second defang written for a second consumer is how one
+ * of them comes to know about a delimiter the other emits: a forged `[END …]` token that the
+ * emitting site happens not to defang closes its fence early and the attacker's lines land OUTSIDE
+ * the boundary, reading as first-party text. {@link defangUntrustedDelimiters} knows **every**
+ * delimiter we emit, so every consumer is protected by every arm.
+ *
+ * **Defang BEFORE wrapping, always.** That ordering is the whole mechanism; wrapping first and
+ * sanitizing after would sanitize a string that already contains the real delimiters.
+ */
+/** The MCP discovery-instructions fence (EXT-32), emitted by `utils/systemPromptNotes.ts`. */
+export declare const MCP_FENCE_BEGIN = "[BEGIN MCP SERVER-PROVIDED CONTEXT]";
+export declare const MCP_FENCE_END = "[END MCP SERVER-PROVIDED CONTEXT]";
+/**
+ * EXT-65 — the fence a refused command is quoted back inside, emitted by
+ * `core/shell/abstention.ts`. A command the gate could not parse is frequently a command the model
+ * assembled out of text it read somewhere, so quoting it back for the model to rewrite is quoting
+ * untrusted bytes into the model's context.
+ */
+export declare const QUOTED_COMMAND_FENCE_BEGIN = "[BEGIN QUOTED COMMAND TEXT]";
+export declare const QUOTED_COMMAND_FENCE_END = "[END QUOTED COMMAND TEXT]";
+/** How much of a refused command is quoted back. Generous; a realistic command is far shorter. */
+export declare const QUOTED_COMMAND_MAX_CHARS = 2000;
+/** Appended when {@link QUOTED_COMMAND_MAX_CHARS} actually clipped the quoted command. */
+export declare const QUOTED_COMMAND_TRUNCATION_MARKER = "\u2026 [truncated]";
+/**
+ * [[EXT-46]] — the fence the ACP server quotes a prompt's non-text content blocks inside, emitted by
+ * `@gaunt-sloth/agent`'s `modules/acp/acpAgentApp.ts`.
+ *
+ * An ACP client attaches content blocks to a prompt, and the ones that are not the user's own typed
+ * text carry values the user did not author: a resource link's `name`, `uri` and `description` come
+ * from the editor, the filesystem or an MCP server, and a block's `type` is an arbitrary client
+ * string by the v2 schema. The agent has to tell the model that something was attached — dropping it
+ * silently is worse — so those values are quoted into the same message as the user's words, which is
+ * the situation this module exists for.
+ */
+export declare const ACP_ATTACHMENT_FENCE_BEGIN = "[BEGIN CLIENT-PROVIDED ATTACHMENT]";
+export declare const ACP_ATTACHMENT_FENCE_END = "[END CLIENT-PROVIDED ATTACHMENT]";
+/**
+ * How much of one attachment FIELD is quoted. These are metadata (a file name, a URI, a one-line
+ * description), not documents, so this is generous rather than a limit anything real should reach.
+ */
+export declare const ACP_ATTACHMENT_FIELD_MAX_CHARS = 1000;
+/** Appended when {@link ACP_ATTACHMENT_FIELD_MAX_CHARS} actually clipped a field. */
+export declare const ACP_ATTACHMENT_TRUNCATION_MARKER = "\u2026 [truncated]";
+/**
+ * Neutralize every structural delimiter this codebase emits, inside UNTRUSTED text.
+ *
+ * The text is fully attacker-influenceable, so it may forge:
+ *   - any fence's tokens (`[BEGIN|END MCP SERVER-PROVIDED CONTEXT]`,
+ *     `[BEGIN|END QUOTED COMMAND TEXT]`, `[BEGIN|END CLIENT-PROVIDED ATTACHMENT]`) — the bracket run
+ *     is collapsed so they can no longer be read as the real delimiter, while staying legible to a
+ *     reader who wants to see what was attempted; and
+ *   - a per-server label line `--- Server: …` (EXT-32) — the leading `---` run is broken so it
+ *     cannot masquerade as one of ours.
+ *
+ * After this, the ONLY real delimiters in a composed block are the ones the caller emits. Names we
+ * put in our OWN labels come from trusted config keys and are not sanitized — only the untrusted
+ * CONTENT is.
+ *
+ * Whitespace-tolerant (`\s+`, optional bracket padding, `-{3,}`) so trivial spacing variants cannot
+ * slip a delimiter through, and case-insensitive so neither can a lowercase one.
+ */
+export declare function defangUntrustedDelimiters(text: string): string;
+/**
+ * Truncate untrusted text at `maxChars`, SURROGATE-SAFE, appending `marker` only when text was
+ * actually clipped.
+ *
+ * A naive `slice(0, N)` can split a surrogate pair (e.g. an emoji) at the boundary and emit a lone
+ * half-code-unit. If the cut would land between a high and a low surrogate, back off one code unit
+ * so the pair is kept whole (dropped entirely rather than split).
+ */
+export declare function capUntrustedText(text: string, maxChars: number, marker: string): string;

package/dist/utils/untrustedText.js

@@ -0,0 +1,101 @@
+/**
+ * @module utils/untrustedText
+ *
+ * **The structural delimiters gsloth wraps untrusted text in, and the one function that neutralizes
+ * a forged one.**
+ *
+ * Text that arrived from outside this process — an MCP server's discovery `instructions`, a command
+ * string the model composed from an issue body or a fetched page — is quoted into the model's
+ * context in several places. Wherever it is, the same two things have to be true:
+ *
+ * 1. the quoted text is visibly fenced, so the model can tell data from first-party instruction; and
+ * 2. **the quoted text cannot forge the fence** and escape it.
+ *
+ * (2) is the load-bearing half, and it is why the delimiters and the defang live together in one
+ * module rather than beside each consumer. A second defang written for a second consumer is how one
+ * of them comes to know about a delimiter the other emits: a forged `[END …]` token that the
+ * emitting site happens not to defang closes its fence early and the attacker's lines land OUTSIDE
+ * the boundary, reading as first-party text. {@link defangUntrustedDelimiters} knows **every**
+ * delimiter we emit, so every consumer is protected by every arm.
+ *
+ * **Defang BEFORE wrapping, always.** That ordering is the whole mechanism; wrapping first and
+ * sanitizing after would sanitize a string that already contains the real delimiters.
+ */
+/** The MCP discovery-instructions fence (EXT-32), emitted by `utils/systemPromptNotes.ts`. */
+export const MCP_FENCE_BEGIN = '[BEGIN MCP SERVER-PROVIDED CONTEXT]';
+export const MCP_FENCE_END = '[END MCP SERVER-PROVIDED CONTEXT]';
+/**
+ * EXT-65 — the fence a refused command is quoted back inside, emitted by
+ * `core/shell/abstention.ts`. A command the gate could not parse is frequently a command the model
+ * assembled out of text it read somewhere, so quoting it back for the model to rewrite is quoting
+ * untrusted bytes into the model's context.
+ */
+export const QUOTED_COMMAND_FENCE_BEGIN = '[BEGIN QUOTED COMMAND TEXT]';
+export const QUOTED_COMMAND_FENCE_END = '[END QUOTED COMMAND TEXT]';
+/** How much of a refused command is quoted back. Generous; a realistic command is far shorter. */
+export const QUOTED_COMMAND_MAX_CHARS = 2000;
+/** Appended when {@link QUOTED_COMMAND_MAX_CHARS} actually clipped the quoted command. */
+export const QUOTED_COMMAND_TRUNCATION_MARKER = '… [truncated]';
+/**
+ * [[EXT-46]] — the fence the ACP server quotes a prompt's non-text content blocks inside, emitted by
+ * `@gaunt-sloth/agent`'s `modules/acp/acpAgentApp.ts`.
+ *
+ * An ACP client attaches content blocks to a prompt, and the ones that are not the user's own typed
+ * text carry values the user did not author: a resource link's `name`, `uri` and `description` come
+ * from the editor, the filesystem or an MCP server, and a block's `type` is an arbitrary client
+ * string by the v2 schema. The agent has to tell the model that something was attached — dropping it
+ * silently is worse — so those values are quoted into the same message as the user's words, which is
+ * the situation this module exists for.
+ */
+export const ACP_ATTACHMENT_FENCE_BEGIN = '[BEGIN CLIENT-PROVIDED ATTACHMENT]';
+export const ACP_ATTACHMENT_FENCE_END = '[END CLIENT-PROVIDED ATTACHMENT]';
+/**
+ * How much of one attachment FIELD is quoted. These are metadata (a file name, a URI, a one-line
+ * description), not documents, so this is generous rather than a limit anything real should reach.
+ */
+export const ACP_ATTACHMENT_FIELD_MAX_CHARS = 1000;
+/** Appended when {@link ACP_ATTACHMENT_FIELD_MAX_CHARS} actually clipped a field. */
+export const ACP_ATTACHMENT_TRUNCATION_MARKER = '… [truncated]';
+/**
+ * Neutralize every structural delimiter this codebase emits, inside UNTRUSTED text.
+ *
+ * The text is fully attacker-influenceable, so it may forge:
+ *   - any fence's tokens (`[BEGIN|END MCP SERVER-PROVIDED CONTEXT]`,
+ *     `[BEGIN|END QUOTED COMMAND TEXT]`, `[BEGIN|END CLIENT-PROVIDED ATTACHMENT]`) — the bracket run
+ *     is collapsed so they can no longer be read as the real delimiter, while staying legible to a
+ *     reader who wants to see what was attempted; and
+ *   - a per-server label line `--- Server: …` (EXT-32) — the leading `---` run is broken so it
+ *     cannot masquerade as one of ours.
+ *
+ * After this, the ONLY real delimiters in a composed block are the ones the caller emits. Names we
+ * put in our OWN labels come from trusted config keys and are not sanitized — only the untrusted
+ * CONTENT is.
+ *
+ * Whitespace-tolerant (`\s+`, optional bracket padding, `-{3,}`) so trivial spacing variants cannot
+ * slip a delimiter through, and case-insensitive so neither can a lowercase one.
+ */
+export function defangUntrustedDelimiters(text) {
+    return text
+        .replace(/\[\s*(BEGIN|END)\s+MCP\s+SERVER-PROVIDED\s+CONTEXT\s*\]/gi, (_m, kw) => `(server text: ${kw.toUpperCase()} MCP SERVER-PROVIDED CONTEXT)`)
+        .replace(/\[\s*(BEGIN|END)\s+QUOTED\s+COMMAND\s+TEXT\s*\]/gi, (_m, kw) => `(quoted text: ${kw.toUpperCase()} QUOTED COMMAND TEXT)`)
+        .replace(/\[\s*(BEGIN|END)\s+CLIENT-PROVIDED\s+ATTACHMENT\s*\]/gi, (_m, kw) => `(client text: ${kw.toUpperCase()} CLIENT-PROVIDED ATTACHMENT)`)
+        .replace(/-{3,}(\s*Server\s*:)/gi, '- - -$1');
+}
+/**
+ * Truncate untrusted text at `maxChars`, SURROGATE-SAFE, appending `marker` only when text was
+ * actually clipped.
+ *
+ * A naive `slice(0, N)` can split a surrogate pair (e.g. an emoji) at the boundary and emit a lone
+ * half-code-unit. If the cut would land between a high and a low surrogate, back off one code unit
+ * so the pair is kept whole (dropped entirely rather than split).
+ */
+export function capUntrustedText(text, maxChars, marker) {
+    if (text.length <= maxChars)
+        return text;
+    let end = maxChars;
+    const code = text.charCodeAt(end - 1);
+    if (code >= 0xd800 && code <= 0xdbff)
+        end -= 1; // don't split a surrogate pair
+    return `${text.slice(0, end).trimEnd()}\n${marker}`;
+}
+//# sourceMappingURL=untrustedText.js.map

package/dist/utils/untrustedText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"untrustedText.js","sourceRoot":"","sources":["../../src/utils/untrustedText.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,8FAA8F;AAC9F,MAAM,CAAC,MAAM,eAAe,GAAG,qCAAqC,CAAC;AACrE,MAAM,CAAC,MAAM,aAAa,GAAG,mCAAmC,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,6BAA6B,CAAC;AACxE,MAAM,CAAC,MAAM,wBAAwB,GAAG,2BAA2B,CAAC;AAEpE,kGAAkG;AAClG,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAE7C,0FAA0F;AAC1F,MAAM,CAAC,MAAM,gCAAgC,GAAG,eAAe,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,oCAAoC,CAAC;AAC/E,MAAM,CAAC,MAAM,wBAAwB,GAAG,kCAAkC,CAAC;AAE3E;;;GAGG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,IAAI,CAAC;AAEnD,qFAAqF;AACrF,MAAM,CAAC,MAAM,gCAAgC,GAAG,eAAe,CAAC;AAEhE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,OAAO,IAAI;SACR,OAAO,CACN,2DAA2D,EAC3D,CAAC,EAAE,EAAE,EAAU,EAAE,EAAE,CAAC,iBAAiB,EAAE,CAAC,WAAW,EAAE,+BAA+B,CACrF;SACA,OAAO,CACN,mDAAmD,EACnD,CAAC,EAAE,EAAE,EAAU,EAAE,EAAE,CAAC,iBAAiB,EAAE,CAAC,WAAW,EAAE,uBAAuB,CAC7E;SACA,OAAO,CACN,wDAAwD,EACxD,CAAC,EAAE,EAAE,EAAU,EAAE,EAAE,CAAC,iBAAiB,EAAE,CAAC,WAAW,EAAE,8BAA8B,CACpF;SACA,OAAO,CAAC,wBAAwB,EAAE,SAAS,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,QAAgB,EAAE,MAAc;IAC7E,IAAI,IAAI,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,GAAG,GAAG,QAAQ,CAAC;IACnB,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IACtC,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM;QAAE,GAAG,IAAI,CAAC,CAAC,CAAC,+BAA+B;IAC/E,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;AACtD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaunt-sloth/core",
-  "version": "2.0.0-alpha.8",
+  "version": "2.0.0-beta.0",
   "description": "Core utilities and types for Gaunt Sloth",
   "license": "MIT",
   "author": "Andrew Kondratev",
@@ -30,19 +30,22 @@
     "#src/*.js": "./dist/*.js"
   },
   "dependencies": {
-    "@langchain/core": "^1.2.1",
-    "@langchain/langgraph": "^1.4.7",
+    "@langchain/core": "^1.2.5",
+    "@langchain/langgraph": "^1.4.9",
     "jiti": "^2.7.0",
     "jsonc-parser": "^3.3.1",
-    "langchain": "^1.5.2",
-    "zod": "^4.0.0"
+    "langchain": "^1.5.5",
+    "string-width": "^8.2.2",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@langchain/anthropic": "^1.5.0",
     "@langchain/deepseek": "^1.1.1",
     "@langchain/google": "^0.2.0",
     "@langchain/groq": "^1.3.0",
+    "@langchain/ollama": "^1.3.0",
     "@langchain/openai": "^1.5.1",
+    "@langchain/openrouter": "^0.4.5",
     "@langchain/xai": "^1.4.1"
   },
   "peerDependenciesMeta": {
@@ -58,9 +61,15 @@
     "@langchain/groq": {
       "optional": true
     },
+    "@langchain/ollama": {
+      "optional": true
+    },
     "@langchain/openai": {
       "optional": true
     },
+    "@langchain/openrouter": {
+      "optional": true
+    },
     "@langchain/xai": {
       "optional": true
     }
@@ -71,10 +80,15 @@
     ".gsloth.*.md"
   ],
   "publishConfig": {
-    "tag": "alpha"
+    "tag": "beta"
+  },
+  "devDependencies": {
+    "ajv": "8.20.0",
+    "typedoc": "^0.28.20"
   },
   "scripts": {
     "build": "tsc",
-    "schema:generate": "node scripts/generate-config-schema.mjs"
+    "schema:generate": "node scripts/generate-config-schema.mjs",
+    "surface:generate": "node scripts/generate-type-surface.mjs"
   }
 }