stitchkit 0.90.4 → 0.90.5

package/dist/tools/connections/index.js

@@ -6,6 +6,12 @@ import {
   withDefsDialect
 } from "../../index-fenaekmk.js";
 import"../../index-cby4ar3v.js";
+import {
+  AppError
+} from "../../index-scs3f1eg.js";
+import {
+  safeJsonParse
+} from "../../index-kzfs85xp.js";
 import {
   isRecord
 } from "../../index-77fekveh.js";
@@ -514,6 +520,34 @@ class McpHttpClient {
   }
 }
 
+// src/tools/connections/mcp-envelope.ts
+function unwrapMcpResult(result) {
+  if (!isRecord(result))
+    return result;
+  if (result.structuredContent !== undefined)
+    return result.structuredContent;
+  if (!Array.isArray(result.content))
+    return result;
+  const only = result.content.length === 1 ? result.content[0] : undefined;
+  if (!isRecord(only) || only.type !== "text" || typeof only.text !== "string")
+    return result;
+  try {
+    return safeJsonParse(only.text);
+  } catch {
+    return only.text;
+  }
+}
+var UPSTREAM_TOOL_ERROR = "UPSTREAM_TOOL_ERROR";
+function mcpToolFailure(toolName, result) {
+  const payload = unwrapMcpResult(result);
+  if (isRecord(payload) && typeof payload.error === "string") {
+    const details = isRecord(payload.details) ? payload.details : undefined;
+    const message = typeof details?.message === "string" ? details.message : payload.error;
+    return new AppError(payload.error, message, 502, details);
+  }
+  return new AppError(UPSTREAM_TOOL_ERROR, `External MCP tool "${toolName}" returned an error`, 502, payload === undefined ? undefined : { upstream: payload });
+}
+
 // src/tools/connections/runtime.ts
 import { z } from "zod";
 async function withConnectionToken(params, body) {
@@ -608,10 +642,9 @@ async function mountMcpConnection(connection, instanceId, onSkipped) {
         return withConnectionToken({ instanceId, provider: connection.token, client, context }, async (token) => {
           await client.initialize(token, context.signal);
           const result = await client.request("tools/call", { name, arguments: context.input }, token, context.signal);
-          if (isRecord(result) && result.isError === true) {
-            throw new Error(`External MCP tool "${name}" returned an error`);
-          }
-          return result;
+          if (isRecord(result) && result.isError === true)
+            throw mcpToolFailure(name, result);
+          return context.source === "cli" ? unwrapMcpResult(result) : result;
         }).finally(() => client.teardown());
       }
     });

package/dist/tools/connections/mcp-envelope.d.ts

@@ -0,0 +1,44 @@
+/**
+ * What a discovered MCP tool's answer is, per transport.
+ *
+ * `tools/call` returns an envelope — `{ content: [...], structuredContent? }` —
+ * and an agent mount needs exactly that: the parts are what a model is shown.
+ * The CLI transport is different in kind, because the handler's value is what
+ * gets printed, piped and aggregated. Handed the envelope, `--count-by status`
+ * groups the *parts* and answers `no record carries the field "status" —
+ * available: text, type`, and `--json` emits the answer as a JSON string nested
+ * inside `content[0].text`, so every consumer unwraps before anything works.
+ *
+ * So the CLI unwraps, and only the CLI. The order is the server's own order of
+ * preference: `structuredContent` is the answer when the server sent one; a lone
+ * text part is the answer when it parses as JSON, and its text when it does not.
+ * Anything else — several parts, an image, audio — is passed through whole,
+ * because picking one part out of many would be inventing an answer.
+ */
+import { AppError } from '../../contract/errors.js';
+export declare function unwrapMcpResult(result: unknown): unknown;
+/**
+ * The class a relayed failure carries when the server sent no structured body.
+ *
+ * Not `INTERNAL_SERVER_ERROR`: nothing of ours broke. The honest statement is
+ * that the call failed upstream and we cannot say more than the server did.
+ */
+export declare const UPSTREAM_TOOL_ERROR = "UPSTREAM_TOOL_ERROR";
+/**
+ * Turn a failed `CallToolResult` into the error the caller can act on.
+ *
+ * The line this replaces threw a one-sentence `Error` and discarded the result,
+ * which cost three things at once: the code (so `exitCodes` had nothing to map
+ * and every remote failure exited `1`), the message the operator needed, and the
+ * error's own class — a plain `Error` is an *unexpected* error to the runner, so
+ * it printed a code frame of the framework bundle before the JSON failure and
+ * was then scrubbed to a bare `INTERNAL_SERVER_ERROR`.
+ *
+ * A structured `{ error, details }` body is the remote contract's own refusal
+ * and is relayed as one. Anything else keeps the framework's sentence and
+ * carries what the server did send — reporting less than we have is not caution.
+ * The status is 502 either way: whatever the code says, the failure happened
+ * upstream, and a consumer re-serving it over HTTP should say so.
+ */
+export declare function mcpToolFailure(toolName: string, result: unknown): AppError;
+//# sourceMappingURL=mcp-envelope.d.ts.map

package/dist/tools/connections/mcp-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-envelope.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/mcp-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAIjD,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAaxD;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,QAAQ,CAa1E"}

package/dist/tools/connections/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/mcp.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGhF,OAAO,EACL,KAAK,0BAA0B,EAIhC,MAAM,WAAW,CAAC;AAGnB,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,SAAS,CAAC;AAQlE,gEAAgE;AAChE,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,mBAAmB,EAC/B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,0BAA0B,GACpC,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAgElC"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/mcp.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAIhF,OAAO,EACL,KAAK,0BAA0B,EAIhC,MAAM,WAAW,CAAC;AAGnB,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,SAAS,CAAC;AAQlE,gEAAgE;AAChE,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,mBAAmB,EAC/B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,0BAA0B,GACpC,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAqElC"}

package/dist/tools.js

@@ -21,7 +21,7 @@ import {
   buildToolManifest,
   describeToolCatalog,
   mountAgent
-} from "./index-19ryv24q.js";
+} from "./index-83fafqw8.js";
 import"./index-7rkhw9ec.js";
 import {
   argumentsDigest
@@ -37,7 +37,7 @@ import {
 } from "./index-4fpa9dy2.js";
 import {
   createToolInvoker
-} from "./index-7t0wq6j5.js";
+} from "./index-tgh3ksfh.js";
 import {
   WaitTimeoutError,
   createCli,
@@ -46,22 +46,22 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "./index-y47z614h.js";
+} from "./index-fqg5mfk7.js";
 import"./index-sbdmyz75.js";
 import {
   collectToolSurface
-} from "./index-kzxpsf8y.js";
+} from "./index-zsdgd1tz.js";
 import {
   collectTools,
   createToolRunner,
   formatToolError
-} from "./index-32vjke6q.js";
+} from "./index-1bnkzq95.js";
 import {
   ToolExecutionControlError,
   executeToolMethod,
   isToolExecutionControlError,
   toolResultFromError
-} from "./index-vcnfwrtr.js";
+} from "./index-8pjqv3zh.js";
 import {
   getRequestContext,
   getTraceId,
@@ -78,17 +78,12 @@ import {
   ManagedFilePathSchema,
   ManagedFileRefSchema
 } from "./index-6k1937bx.js";
-import {
-  AppError,
-  STITCH_ERROR_STATUS
-} from "./index-scs3f1eg.js";
 import {
   resolvePropagationContext
 } from "./index-zcgf3gqf.js";
 import {
   coerceJsonArgs
 } from "./index-7zbps32p.js";
-import"./index-kzfs85xp.js";
 import {
   createRuntimeToolFactory,
   defineRuntimeTool
@@ -105,6 +100,11 @@ import {
   validateMcpRoundPolicy
 } from "./index-fenaekmk.js";
 import"./index-cby4ar3v.js";
+import {
+  AppError,
+  STITCH_ERROR_STATUS
+} from "./index-scs3f1eg.js";
+import"./index-kzfs85xp.js";
 import {
   isRecord
 } from "./index-77fekveh.js";

package/dist/tracking.js

@@ -5,8 +5,8 @@ import {
   defineContract
 } from "./index-kazec06k.js";
 import"./index-6k1937bx.js";
-import"./index-scs3f1eg.js";
 import"./index-zcgf3gqf.js";
+import"./index-scs3f1eg.js";
 import"./index-kzfs85xp.js";
 import"./index-77fekveh.js";
 

package/llms-full.txt

@@ -7489,9 +7489,12 @@ same Zod schema an HTTP or MCP call does.
 | `--quiet`             | Suppress non-essential stderr output                       |
 | `--dry-run`           | Print the resolved call without executing                  |
 | `--help`, `-h`        | Usage — top-level or per-command flag table                |
+| `--help <text>`       | List only the commands matching a substring                |
 | `--count-by <field>`  | Count records per distinct value — see [Aggregate views](#aggregate-views) |
 | `--sum <f> [--by <g>]`| Total a numeric field, optionally grouped                  |
-| `--top <n> --by <f>`  | Keep only the n largest groups                             |
+| `--sort <field>`      | Order records by a field, largest first                    |
+| `--ascending`         | Flip `--sort` to smallest first                            |
+| `--top <n>`           | Keep the n leading entries of the view asked for           |
 | `--table <a,b>`       | Render named fields as an aligned table                    |
 
 stdout carries the result; structured errors and progress go to stderr. With
@@ -7502,6 +7505,34 @@ diagnostics remain ordinary stderr text. This keeps stdout pipeable and
 `VALIDATION_ERROR → 1`, `UNAUTHORIZED → 2`, `FORBIDDEN → 3`, `NOT_FOUND → 4`,
 …) — override per app with `exitCodes`.
 
+### A narrower question than "all of them"
+
+On a discovered surface `--help` is the only way to learn what exists, and that
+can be two hundred commands. At that size the list stops being an answer: it
+scrolls past a person and costs an agent the same context an unfiltered result
+would. So there is a question between "one command" and "all of them":
+
+```bash
+myapp --help broadcast     # also: -h broadcast · help broadcast · --help=broadcast
+```
+
+```
+Commands matching "broadcast" (3 of 205):
+  broadcast_send    Send a broadcast to every subscriber
+  broadcast_cancel  Stop a running broadcast
+  announce_publish  Publish an announcement as a broadcast
+```
+
+The description is searched as well as the name, because the word someone knows
+is often in the sentence rather than the name — `announce_publish` above is
+matched that way. The count says what was left out.
+
+**No match is an exit code**, not an empty success: `0` over an empty list reads
+as "there are none", which is a different statement from "none of these". It
+exits with whatever `NOT_FOUND` maps to (`4` by default). Bare `--help` is
+unchanged, and `--help=false` still means what it always did — the reserved
+boolean's negation — so one value never carries two meanings.
+
 ## Application global options
 
 `--json` and friends above are the framework's. An application usually has
@@ -7632,9 +7663,20 @@ myapp item_list --top 5 --by status        # same view, written the other way ro
 myapp item_list --table id,status          # the one human-facing shape
 ```
 
-`--by` always names the **grouping** field, in every form it appears in, so the
-grammar has one meaning rather than two. Groups are ordered largest first, which
-is what makes `--top` a defined slice rather than an arbitrary one.
+Two words, one each: **`--by` groups, `--sort` orders.** That leaves `--top` a
+single meaning everywhere — *the n leading entries of the view you asked for* —
+so the question a CLI actually gets asked composes out of the parts:
+
+```bash
+myapp item_list --top 5 --sort messages --table id,messages   # the five biggest, as a table
+myapp item_list --sort messages --top 5 --json                # the same five, as records
+myapp item_list --sort name --ascending                       # ordered the other way
+```
+
+Groups come back largest first for the same reason. A record that carries no
+value for the sort field sorts **last in both directions**: it is not the
+smallest, it is not on the scale at all, and letting it lead an ascending list
+would answer a question nobody asked.
 
 Three rules worth knowing before you rely on them:
 
@@ -7646,6 +7688,8 @@ Three rules worth knowing before you rely on them:
   over an object with two array fields, is refused rather than guessed.
 - **Without a view flag the output is byte-for-byte what it was.** The flags are
   reserved CLI behaviour like `--json`; they never reach a tool argument.
+- **Ordering and grouping do not mix.** `--sort` with `--by`, `--count-by` or
+  `--sum` is refused rather than given a second meaning.
 
 A failed call still reports its own error and exit code. An aggregate over an
 error is not an answer to the question that was asked.
@@ -7725,8 +7769,12 @@ import {
 // otherwise everyone who already installed it never receives the fix.
 assertCliPublishable(previous, next)
 
-// Serving: one generated script per target, no JSON on the wire.
-renderCliInstaller({ manifest, asset: selectCliBuildAsset(manifest, target)!, binaryName: 'myapp' })
+// Serving: omit `asset` and one script covers every published target, selecting
+// by uname at run time — otherwise that dispatch is the last hand-written piece
+// of the install path, and every publisher writes the same x86_64 → x64 table.
+renderCliInstaller({ manifest, binaryName: 'myapp' })
+// Or pin one target explicitly:
+renderCliInstaller({ manifest, asset: selectCliBuildAsset(manifest, target), binaryName: 'myapp' })
 
 // Checking: bounded, at most once per interval, silent on any failure.
 const check = await checkCliUpdate({ manifestUrl, currentVersion, lastCheckedAt })
@@ -7772,6 +7820,28 @@ One unconvertible schema no longer takes the connection down with it. The tool
 is skipped and **named** (`onSkippedTool`, or a stderr line by default), so a
 surface of two hundred tools is not lost to one.
 
+**A remote refusal keeps its code.** A failed `tools/call` used to become a
+one-sentence `Error` with the result discarded, which cost three things at once:
+the code (so `exitCodes` had nothing to map and every remote failure exited `1`),
+the message the operator needed, and the error's own class — a plain `Error` is
+an *unexpected* error to the runner, so it printed a code frame of the framework
+bundle before the JSON failure and was then scrubbed to `INTERNAL_SERVER_ERROR`.
+A structured `{ error, details }` body is now relayed as the contract error it
+is, on every transport; anything else fails as `UPSTREAM_TOOL_ERROR` carrying
+what the server did send. Not `INTERNAL_SERVER_ERROR`, because nothing of ours
+broke.
+
+**On the CLI a discovered command prints the answer, not the envelope.**
+`tools/call` returns `{ content: [...], structuredContent? }`, and an agent mount
+needs exactly that — the parts are what a model is shown. The CLI is different in
+kind, because the handler's value is what gets printed, piped and aggregated:
+handed the envelope, `--count-by status` groups the *content parts* and answers
+`no record carries the field "status" — available: text, type`. So the CLI
+transport unwraps, and only it: `structuredContent` when the server sent one, a
+lone text part when it parses as JSON, its text when it does not. Several parts,
+an image or audio pass through whole — picking one of many would be inventing an
+answer.
+
 
 ## Auth parity
 
@@ -17224,11 +17294,11 @@ SDK nor the `ai` peer.
 | `CliBuildAssetSchema` / `CliBuildAsset` | schema / _type_ | one download; `size` and `sha256` describe the **decompressed** bytes |
 | `CliBuildTargetSchema` / `CliBuildTarget` | schema / _type_ | `{ platform, arch }` |
 | `CliBuildStampSchema` / `CliBuildStamp` | schema / _type_ | the version/commit/build time carried inside a binary |
-| `CliInstallerConfig` | _type_ | manifest, asset, binary name and default install directory |
+| `CliInstallerConfig` | _type_ | manifest, binary name, default install directory, and an optional `asset` — omit it for one script that selects the target by `uname` |
 | `CliUpdateCheckConfig` / `CliUpdateCheck` | _type_ | check inputs, and its four answers — `skipped`, `current`, `outdated`, `unknown` |
 | `CliUpdateApplyConfig` / `AppliedCliUpdate` | _type_ | apply inputs and the replaced path, byte count and digest |
 | `CliProfileStore` / `CliProfileStoreConfig` / `ResolvedCliProfile` | _type_ | the profile store, its directory/schema/hint config, and one resolution |
-| `CliResultView` | _type_ | the requested aggregate — `count`, `sum` or `table` |
+| `CliResultView` | _type_ | the requested view — `count`, `sum`, or `records` (ordered and/or table-rendered) |
 | `CliViewOutput` | _type_ | a JSON value, or the one human-facing text shape |
 | `CliGlobalOptionsParse` | _type_ | `{ argv, globals }` returned by `extractCliGlobalOptions` |
 | `CliArgvRoute` | _type_ | `{ command, commandArgv, topLevelHelp, version, error? }` returned by `routeCliArgv` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.90.4",
+  "version": "0.90.5",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",

package/dist/{index-8crm1srv.js → index-3yqgj323.js}

@@ -18,13 +18,13 @@ import {
   probeAgentProcessSandbox,
   refuseMissingCodingPath
 } from "./index-gte38nbm.js";
+import {
+  defineRuntimeTool
+} from "./index-8z9we758.js";
 import {
   conflict,
   forbidden
 } from "./index-scs3f1eg.js";
-import {
-  defineRuntimeTool
-} from "./index-8z9we758.js";
 
 // src/agent-runtime/coding-tool-contract.ts
 import { z } from "zod";

package/dist/{index-vcnfwrtr.js → index-8pjqv3zh.js}

@@ -7,20 +7,20 @@ import {
   normalizeError,
   validateDeclaredOutput
 } from "./index-2hryh65w.js";
+import {
+  coerceJsonArgs
+} from "./index-7zbps32p.js";
+import {
+  objectShapeKeys
+} from "./index-fenaekmk.js";
 import {
   AppError,
   STITCH_ERROR_STATUS,
   isStitchErrorCode
 } from "./index-scs3f1eg.js";
-import {
-  coerceJsonArgs
-} from "./index-7zbps32p.js";
 import {
   isUnsafeKey
 } from "./index-kzfs85xp.js";
-import {
-  objectShapeKeys
-} from "./index-fenaekmk.js";
 import {
   isRecord
 } from "./index-77fekveh.js";

package/dist/{index-db51n3xr.js → index-ra6txecz.js}

@@ -47,14 +47,14 @@ import {
   joinRoutePath,
   parseTrailingWildcard
 } from "./index-kazec06k.js";
+import {
+  resolveTraceContext
+} from "./index-zcgf3gqf.js";
 import {
   AppError,
   badRequest,
   forbidden
 } from "./index-scs3f1eg.js";
-import {
-  resolveTraceContext
-} from "./index-zcgf3gqf.js";
 import {
   isUnsafeKey,
   safeJsonParse