@kya-os/mcp 1.18.0 → 1.20.0

package/dist/middleware/with-kya-os.session.d.ts

@@ -5,9 +5,17 @@
  * live here, so the borrowing semantics are preserved exactly) and the two proof
  * paths: `wrapWithProof` (success responses) and `attachOutcomeProof` (denied /
  * step-up / needs-authorization outcomes). Extracted from `./with-kya-os.ts`.
+ *
+ * Neither path signs in the handler. The MCP SDK changes a result after the
+ * handler returns: SDK 2 adds `resultType` on the 2026-07-28 revision, which
+ * the envelope profile covers; both SDKs fill in a missing `content`, and SDK
+ * 2 appends a text item to `content` when `structuredContent` is not an
+ * object, which the body profile covers. Both paths therefore leave the proof
+ * to the outer layer, the withKyaOs transport, which makes it over the result
+ * it sends, under either profile.
  */
-import type { KyaOsToolHandler } from "./with-kya-os.types.js";
-import type { MiddlewareDeps, AttachOutcomeProof } from "./with-kya-os.deps.js";
+import type { KyaOsToolHandler, KyaOsToolResult } from "./with-kya-os.types.js";
+import type { MiddlewareDeps, AttachOutcomeProof, RequireProofLayer } from "./with-kya-os.deps.js";
 /**
  * The private `_meta` member a middleware's wrappers stamp their results with
  * while an outer layer (the withKyaOs transport) reads them. It holds a random
@@ -17,7 +25,16 @@ import type { MiddlewareDeps, AttachOutcomeProof } from "./with-kya-os.deps.js";
  * that.
  */
 export declare const LIFECYCLE_STAMP_META_KEY = "org.kya-os/lifecycle-stamp";
-type ToolResult = Awaited<ReturnType<KyaOsToolHandler>>;
+/**
+ * The private `_meta` member that names the proof a wrapper left for the
+ * transport to make: a one-time id. What the proof
+ * claims stays in the middleware, keyed by that id, so code that can write a
+ * result cannot choose the claims. The transport redeems the id only on a
+ * result that also carries the middleware's stamp, and strips it as it strips
+ * the stamp. A string, so a copy of the result carries it too.
+ */
+export declare const PENDING_PROOF_META_KEY = "org.kya-os/pending-proof";
+type ToolResult = KyaOsToolResult;
 /**
  * Remove the `_meta` members only the middleware may set (proofs, proof error,
  * audit marker, lifecycle stamp) from a result it did not produce, keeping
@@ -25,16 +42,62 @@ type ToolResult = Awaited<ReturnType<KyaOsToolHandler>>;
  * is removed.
  */
 export declare function withoutOutcomeMeta<T extends ToolResult>(result: T): T;
-/** Remove the lifecycle stamp, which must never leave the process. */
-export declare function withoutLifecycleStamp<T extends ToolResult>(result: T): T;
+/**
+ * Remove the middleware's private members, which must never leave the
+ * process, from `result` and from everything nested in it, at any depth.
+ */
+export declare function withoutPrivateMeta<T extends ToolResult>(result: T): T;
+/** Any value without the middleware's private `_meta` members, at any depth. */
+export declare function withoutPrivateMembers(value: unknown): unknown;
+/** What the outer layer (the withKyaOs transport) does with a middleware's results. */
+export interface OuterProofLayer {
+    /**
+     * Count one more open transport, until the returned function is called.
+     * The wrappers refuse to run while none is open.
+     * Calling the returned function again does nothing.
+     */
+    open(): () => void;
+    /** Whether the middleware's wrappers returned `result`: it carries their stamp. */
+    owns(result: ToolResult): boolean;
+    /**
+     * `result` as it may leave the process: without the private members, and,
+     * when a wrapper left its proof to the transport, carrying that proof, made
+     * over `result` as it is now. Never throws: a proof that cannot be made is
+     * reported on the result, as one that fails in a wrapper is. A pending
+     * proof is redeemed once, and, when the result answers a `tools/call` the
+     * transport tracked, only by a proof left for that tool (`answering`).
+     */
+    send(result: ToolResult, answering?: {
+        toolName: string;
+    }): Promise<ToolResult>;
+    /**
+     * Any other part of an outgoing message (a notification's or request's
+     * `params`, an error's `data`) as it may leave the process: without the
+     * private members at any depth. A waiting proof whose id is found there
+     * is closed, so nothing can redeem it. Never throws.
+     */
+    scrub(value: unknown): unknown;
+}
 /**
  * Tell the middleware behind `wrapWithProof` that an outer layer (the withKyaOs
  * transport) reads its results. From then on its wrappers stamp what they
- * return with the middleware's token. Returns the check for that stamp, or
+ * return with the middleware's token and leave their proofs to the layer.
+ * Returns the layer's view of those results, or
  * undefined for a middleware this module did not create, whose results are
  * then never treated as its own.
  */
-export declare function attachOuterProofLayer(wrapWithProof: object): ((result: ToolResult) => boolean) | undefined;
+export declare function attachOuterProofLayer(wrapWithProof: object): OuterProofLayer | undefined;
+/**
+ * The fallback session for a call that threaded none, or why there is none:
+ * `ambiguous` when several sessions are live and the middleware refuses to
+ * pick one, which might be another client's.
+ */
+export type FallbackSession = {
+    sessionId: string;
+} | {
+    sessionId: undefined;
+    ambiguous: boolean;
+};
 export interface SessionProof {
     /** Establish a session from a handshake and cache it as the fallback. */
     handleHandshake(args: Record<string, unknown>): Promise<{
@@ -46,14 +109,17 @@ export interface SessionProof {
     }>;
     /**
      * Resolve the single-process fallback session for a call that threaded none —
-     * or auto-create one when `config.autoSession` is set. Returns undefined (skip
-     * the proof) when attribution would be ambiguous (multiple live sessions).
+     * or auto-create one when `config.autoSession` is set. Returns no session
+     * (skip the proof) when there is none, or, marked `ambiguous`, when
+     * attribution would be ambiguous (multiple live sessions).
      */
-    ensureSession(): Promise<string | undefined>;
+    ensureSession(): Promise<FallbackSession>;
     /** Wrap a tool handler to attach a holder-of-key proof to success responses. */
     wrapWithProof<T extends Record<string, unknown> = Record<string, unknown>>(toolName: string, handler: KyaOsToolHandler<T>): KyaOsToolHandler;
     /** Attach a signed proof recording an authorization outcome to a response. */
     attachOutcomeProof: AttachOutcomeProof;
+    /** Refuse a wrapped call whose proof could not be made where it is sent. */
+    requireProofLayer: RequireProofLayer;
 }
 export declare function createSessionProof(deps: MiddlewareDeps): SessionProof;
 export {};