@stratusagent/plugin-mcp 0.11.3 → 0.11.5

package/dist/normalize.d.ts

@@ -1,4 +1,4 @@
-import type { JsonValue } from '@stratusagent/core';
+import { type JsonValue } from '@stratusagent/core';
 import { type TaintedWriteLedger } from '@stratusagent/plugins';
 /**
  * Turning what an MCP server sends back into what a Stratus tool returns:
@@ -20,22 +20,167 @@ import { type TaintedWriteLedger } from '@stratusagent/plugins';
 export declare const sanitizeToolSegment: (raw: string) => string | undefined;
 /** Server keys are operator-chosen and become a name segment; held to the segment shape outright. */
 export declare const SERVER_NAME_PATTERN: RegExp;
+/**
+ * The longest tool description a server gets to put in front of the model.
+ * The same bound a skill's description has (`SKILL_DESCRIPTION_MAX_LENGTH`
+ * in `@stratusagent/agents`), for the same reason: a description is prose
+ * the model reads on every turn, written by a party the operator did not
+ * author, and a paragraph is a description while a page is instructions.
+ */
+export declare const BRIDGED_DESCRIPTION_MAX_LENGTH = 1024;
+/**
+ * A server's tool description as it reaches the registry — and, through
+ * it, every provider's tool block on every turn. The text is the server's,
+ * re-read on every reconnect, and `tools/list` is the one channel a
+ * server has that arrives looking like part of the harness rather than
+ * like a result. Two bounds, neither a filter: control characters and the
+ * Unicode bidi controls are spelled out the way memory entries are (a
+ * right-to-left override in a description is a description that reads
+ * differently to a person than to the model — escaped, it reads as what it
+ * is; the set is Unicode's `Bidi_Control` property, marks and the Arabic
+ * letter mark included, not only the overrides and isolates), and the
+ * length is capped with the cut announced. Newlines and tabs stay: a
+ * description is allowed to be several lines.
+ */
+export declare const bridgedDescription: (raw: string) => string;
+/**
+ * The longest input schema a server gets to put in front of the model, in
+ * characters of its JSON. A schema is read by the provider as structure,
+ * but every string in it lands in the tool block as text, and sixteen
+ * thousand characters of parameter list is a page, not a parameter list.
+ */
+export declare const BRIDGED_SCHEMA_MAX_LENGTH = 16384;
+/**
+ * The most of one `tools/call` result a server gets to put into the
+ * transcript, in characters, counting the joined text and the JSON of
+ * `structuredContent` separately.
+ *
+ * Every first-party tool caps what it returns — `fs.read` at 64 KB,
+ * `shell.run` and `browser.read` at 100 KB, `web.fetch` at 400 KB — and
+ * a bridged result was the one that did not. Binary blocks already land on
+ * disk rather than in the result, so this is about text, and text is the
+ * part that is *durable*: a tool result is saved into the session and
+ * replayed to the provider on every later turn of that conversation, so a
+ * server that answers `list_files` with twenty megabytes does not cost one
+ * turn, it costs every turn until the session ends — and survives restarts,
+ * because the transcript does. The stdio transport bounds a single message
+ * at its reader's buffer (10 MB by default) and the HTTP transports bound
+ * nothing, so "the transport will stop it" was never a cap.
+ *
+ * 100 KB matches `shell.run`, which is the closest comparison: somebody
+ * else's program, writing as much as it likes. Counted in characters
+ * rather than bytes, like the two bounds above and unlike the tool packs':
+ * what is scarce here is the model's context, which is measured in tokens,
+ * and a token follows a character more closely than it follows a byte.
+ */
+export declare const BRIDGED_RESULT_MAX_LENGTH = 100000;
+/**
+ * The smallest `maxResultChars` that means anything, and the floor every
+ * smaller one is raised to.
+ *
+ * A cap has to be able to hold an account of what it cut. The four
+ * annotations a result can carry — a marker for the text, one for the
+ * structured payload, and the two truncation notes — come to a little over
+ * four hundred characters with the keys they arrive under, and shortening
+ * them is not on the table: an announcement is the whole reason a cap is
+ * safe to have, and a cut with nothing saying it happened is the failure
+ * this bound exists to prevent.
+ *
+ * So below this a cap cannot be honoured, only approximated — `1` yielded
+ * 73 characters for a truncated text and 104 for a dropped resource link —
+ * and approximating it silently is worse than raising it. Raised rather
+ * than refused, and raised to the floor rather than back to the default,
+ * because an operator who asked for the smallest possible result should
+ * get the smallest possible result. The markers name the cap that was
+ * actually applied.
+ */
+export declare const BRIDGED_RESULT_MIN_LENGTH = 512;
+/**
+ * A configured `maxResultChars` as it actually applies: the default when
+ * unset, never below the floor. One implementation because it has two
+ * consumers — `normalizeCallResult` for a result, and the call path for a
+ * `tools/call` that fails before there is a result to normalize. A second
+ * copy would leave the floor applying to one and not the other, which is
+ * how a cap of 1 came to name itself in a protocol error's marker.
+ */
+export declare const boundedResultLimit: (configured: number | undefined) => number;
+/**
+ * How deep a schema may nest before the bridge stops walking it. Sixty-four
+ * levels is far past any parameter list a person wrote; a schema nested
+ * deeper is a stack-overflow attempt dressed as a tool, and a recursive
+ * walk that blew the stack during discovery would take the whole server
+ * down as unreachable, and again on every reconnect.
+ */
+export declare const BRIDGED_SCHEMA_MAX_DEPTH = 64;
+/**
+ * The longest name segment a server's tool may bridge under. The segment
+ * is the tail of `mcp.<server>.<segment>`, sent as the tool's name in
+ * every model request, and a name is the one string a server writes that
+ * no description bound touches — a tool called `a` three thousand times
+ * over is a page in the tool block by another route. Sixty-four is the
+ * longest name the strictest provider accepts whole.
+ */
+export declare const BRIDGED_SEGMENT_MAX_LENGTH = 64;
+/**
+ * A server's input schema as it reaches the registry — and, through it,
+ * the tool block of every turn, the same way the description does. The
+ * top-level description is not the only prose in `tools/list`: a
+ * `description` or `title` on any property, at any depth, is text the
+ * model reads too, and it was copied through unbounded. Each is bounded
+ * like the tool's own description. Nothing else in the schema is touched:
+ * a property name, an enum value, a const or a pattern is what the model
+ * sends back in a call, and the bridge forwards arguments to the server
+ * as the model wrote them — a value spelled out here would arrive at the
+ * server as a different value, and the schema would be a lie in the
+ * direction that breaks calls. An annotation key *inside* a literal (an
+ * `enum` member with a `description` field) is data too, and is left
+ * alone — while a *parameter* named `enum` or `default` is a schema like
+ * any other, because the keys of `properties` and `$defs` are names, not
+ * keywords. `undefined` when the bounded schema is still longer than
+ * {@link BRIDGED_SCHEMA_MAX_LENGTH} characters, or nests deeper than
+ * {@link BRIDGED_SCHEMA_MAX_DEPTH}: that tool is not bridged, and the
+ * caller names it.
+ */
+export declare const bridgedSchema: (schema: Record<string, unknown>) => Record<string, unknown> | undefined;
 /** The registered name a server's tool bridges to: `mcp.<server>.<segment>`. */
 export declare const bridgedToolName: (server: string, segment: string) => string;
+/**
+ * Server-written text, bounded for the transcript — the same treatment a
+ * result's text gets, exported because a `tools/call` can fail in ways that
+ * never produce a result at all: a JSON-RPC error, or a transport failure
+ * carrying an HTTP body. Those reach the agent as a thrown message, which
+ * `DefaultExecutor` copies into `ToolResult.error` and the session persists
+ * and replays exactly like output.
+ *
+ * Bounded to the cap *minus the envelope it is replayed in*, for the same
+ * reason a result's fields are: it does not travel as a bare string but as
+ * a JSON string value under a key, and a message cut to exactly the cap
+ * arrives a dozen characters over it. The marker still names the cap the
+ * operator set rather than the number left after that deduction.
+ */
+export declare const THROWN_MESSAGE_ENVELOPE: number;
+export declare const boundServerText: (raw: string, limit: number, what: string) => string;
 export interface NormalizeOptions {
     /** The bridged server's config key — part of where a binary block lands. */
     server: string;
     /** The server-side tool name — part of the written file's name. */
     tool: string;
     /**
-     * The workspace root the host supplied. Binary content lands under
-     * `<workspaceRoot>/<agentId>/mcp/<server>/` — per agent, same as
-     * screenshots, so two agents never read each other's files.
+     * Where this agent's workspace is, asked for rather than passed in — not
+     * a root to join an id onto. Binary content lands under
+     * `<workspace>/mcp/<server>/`, so two agents never read each other's
+     * files, the same shape screenshots take.
+     *
+     * A function because asking is no longer free: the host's seam *creates*
+     * the directory and settles its permissions, and it can fail. A
+     * text-only result must not be reported as an error because a workspace
+     * it never wanted could not be made — the remote call has already
+     * happened, and whoever retries it does the side effect twice.
      */
-    workspaceRoot?: string;
+    workspace?: () => string;
     agentId: string;
     /**
-     * The filesystem provenance ledger for `workspaceRoot`. A binary block
+     * The filesystem provenance ledger for `workspace`. A binary block
      * is a server's bytes written to disk without going through `fs.write`,
      * so the write records itself here at `external` before the bytes land —
      * a later `fs.read` of the file then carries the label the tool result
@@ -43,6 +188,12 @@ export interface NormalizeOptions {
      * the loader-less host case gets.
      */
     ledger?: TaintedWriteLedger;
+    /**
+     * The operator's cap on this result, in characters. Defaults to
+     * {@link BRIDGED_RESULT_MAX_LENGTH}; a server cannot raise it, because
+     * the cap exists to bound what the server sends.
+     */
+    maxResultChars?: number;
     /** Clock seam for deterministic file names in tests. */
     now?: () => number;
 }

package/dist/normalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAc,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEtF;;;;;GAKG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAI1D,CAAC;AAEF,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,QAA0B,CAAC;AAE3D,gFAAgF;AAChF,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAAoC,CAAC;AAkCvG,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,OAAO,EACf,SAAS,gBAAgB,KACxB,OAAO,CAAC,SAAS,CAqInB,CAAC"}
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAIA,OAAO,EAA4C,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC9F,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEtF;;;;;GAKG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAI1D,CAAC;AAEF,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,QAA0B,CAAC;AAE3D;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAUnD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,GAAI,KAAK,MAAM,KAAG,MAWhD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,YAAY,MAAM,GAAG,SAAS,KAAG,MACU,CAAC;AAqR/E;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAU3C;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAoD7C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAazF,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAAoC,CAAC;AA8JvG;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,QAAwB,CAAC;AAE7D,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,EAAE,OAAO,MAAM,EAAE,MAAM,MAAM,KAAG,MACC,CAAC;AAE7E,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,OAAO,EACf,SAAS,gBAAgB,KACxB,OAAO,CAAC,SAAS,CA6BnB,CAAC"}