@mootup/moot-sdk 0.1.0-rc.0 → 0.2.1

package/dist/connect.d.ts

@@ -0,0 +1,10 @@
+import type { MCPClientLike, Session } from './session.js';
+import { MootupNotOrientedError } from './session.js';
+export type { MCPClientLike, Session };
+export { MootupNotOrientedError };
+export interface ConnectMootupOptions {
+    baseUrl: string;
+    auth?: string;
+}
+export declare function connectMootup(client: MCPClientLike, opts: ConnectMootupOptions): Promise<Session>;
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAEtD,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC;AACvC,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAElC,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAkGD,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,OAAO,CAAC,CAqClB"}

package/dist/connect.js

@@ -0,0 +1,126 @@
+// AH-g: connectMootup — thin SDK helper that calls the shipped convo
+// `orientation` MCP tool via a caller-supplied MCP client, surfaces a
+// typed, frozen Session. Session is memoized per-client (inv 10).
+import { MootupNotOrientedError } from './session.js';
+export { MootupNotOrientedError };
+// Per-process, per-MCP-client session cache (inv 10).
+const sessionCache = new WeakMap();
+// Redaction list — error messages must never surface these (inv 11 / T-2).
+const REDACTION_SUBSTRINGS = ['Bearer ', 'Authorization', 'api_key', 'token'];
+function redactError(message) {
+    let out = message;
+    for (const needle of REDACTION_SUBSTRINGS) {
+        if (out.includes(needle)) {
+            out = out.replace(new RegExp(needle, 'gi'), '<redacted>');
+        }
+    }
+    return out;
+}
+function resolveAuth(explicit) {
+    if (explicit)
+        return explicit;
+    const env = globalThis.process?.env ?? {};
+    if (env.MOOTUP_OAUTH_TOKEN)
+        return env.MOOTUP_OAUTH_TOKEN;
+    if (env.MOOTUP_API_KEY)
+        return env.MOOTUP_API_KEY;
+    throw new MootupNotOrientedError('No auth supplied (kwarg > MOOTUP_OAUTH_TOKEN > MOOTUP_API_KEY > error)');
+}
+const JWT_SHAPE_RE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+function validateBaseUrlOrigin(baseUrl, token) {
+    // T-1: if token is JWT-shaped (heuristic OAuth detection), compare the
+    // token's second segment (claims) iss URL origin to baseUrl origin.
+    if (!JWT_SHAPE_RE.test(token))
+        return;
+    const segments = token.split('.');
+    let claims;
+    try {
+        // base64url-decode the claims segment.
+        const b64 = segments[1].replace(/-/g, '+').replace(/_/g, '/');
+        const pad = b64.length % 4 === 0 ? '' : '='.repeat(4 - (b64.length % 4));
+        const decoded = globalThis.atob
+            ? globalThis.atob(b64 + pad)
+            : Buffer.from(b64 + pad, 'base64').toString('binary');
+        claims = JSON.parse(decoded);
+    }
+    catch {
+        return;
+    }
+    if (!claims.iss)
+        return;
+    let issOrigin;
+    let baseOrigin;
+    try {
+        issOrigin = new URL(claims.iss).origin;
+        baseOrigin = new URL(baseUrl).origin;
+    }
+    catch {
+        throw new Error('base_url or OAuth issuer URL is malformed');
+    }
+    if (issOrigin !== baseOrigin) {
+        throw new Error(`base_url origin (${baseOrigin}) does not match OAuth issuer origin (${issOrigin})`);
+    }
+}
+function extractStructured(resp) {
+    if (resp.isError) {
+        throw new Error('orientation tool returned isError=true');
+    }
+    if (resp.structuredContent && typeof resp.structuredContent === 'object') {
+        return resp.structuredContent;
+    }
+    // Fallback: parse the JSON text block if FastMCP emitted only text.
+    const text = resp.content?.find((c) => c.type === 'text')?.text;
+    if (text) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            // fall through to error below
+        }
+    }
+    throw new Error('orientation response missing structuredContent (requires convo ≥AH-g)');
+}
+function makeToolsProxy() {
+    return new Proxy({}, {
+        get(_target, prop) {
+            throw new MootupNotOrientedError(`Typed tool accessors are not yet implemented. Tried to access 'session.tools.${String(prop)}'. Use the caller-supplied MCP client directly until typed accessors ship.`);
+        },
+    });
+}
+export async function connectMootup(client, opts) {
+    const cached = sessionCache.get(client);
+    if (cached)
+        return cached;
+    const token = resolveAuth(opts.auth);
+    try {
+        validateBaseUrlOrigin(opts.baseUrl, token);
+    }
+    catch (err) {
+        throw new Error(redactError(err.message));
+    }
+    let resp;
+    try {
+        resp = await client.callTool({ name: 'orientation', arguments: {} });
+    }
+    catch (err) {
+        throw new Error(redactError(`orientation call failed: ${err.message}`));
+    }
+    const structured = extractStructured(resp);
+    const identity = structured.identity;
+    if (!identity || typeof identity.actor_id !== 'string') {
+        throw new Error('orientation response missing identity.actor_id');
+    }
+    const focus = structured.focus_space;
+    const spaceId = focus && typeof focus.space_id === 'string' ? focus.space_id : null;
+    const contextRaw = structured.context;
+    const orientationSummary = typeof contextRaw === 'string' ? contextRaw : '';
+    const session = Object.freeze({
+        participantId: identity.actor_id,
+        spaceId,
+        orientationSummary,
+        tools: makeToolsProxy(),
+    });
+    sessionCache.set(client, session);
+    return session;
+}
+//# sourceMappingURL=connect.js.map

package/dist/connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,sEAAsE;AACtE,kEAAkE;AAGlE,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAGtD,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAOlC,sDAAsD;AACtD,MAAM,YAAY,GAAG,IAAI,OAAO,EAAmB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,oBAAoB,GAAG,CAAC,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAE9E,SAAS,WAAW,CAAC,OAAe;IAClC,IAAI,GAAG,GAAG,OAAO,CAAC;IAClB,KAAK,MAAM,MAAM,IAAI,oBAAoB,EAAE,CAAC;QAC1C,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACzB,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,WAAW,CAAC,QAAiB;IACpC,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC;IAC1C,IAAI,GAAG,CAAC,kBAAkB;QAAE,OAAO,GAAG,CAAC,kBAAkB,CAAC;IAC1D,IAAI,GAAG,CAAC,cAAc;QAAE,OAAO,GAAG,CAAC,cAAc,CAAC;IAClD,MAAM,IAAI,sBAAsB,CAC9B,wEAAwE,CACzE,CAAC;AACJ,CAAC;AAED,MAAM,YAAY,GAAG,kDAAkD,CAAC;AAExE,SAAS,qBAAqB,CAAC,OAAe,EAAE,KAAa;IAC3D,uEAAuE;IACvE,oEAAoE;IACpE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO;IACtC,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,MAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,uCAAuC;QACvC,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC9D,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;QACzE,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI;YAC7B,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;YAC5B,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,GAAG,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACxD,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAqB,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,GAAG;QAAE,OAAO;IACxB,IAAI,SAAiB,CAAC;IACtB,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,SAAS,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;QACvC,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,SAAS,KAAK,UAAU,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,oBAAoB,UAAU,yCAAyC,SAAS,GAAG,CACpF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,IAI1B;IACC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,IAAI,CAAC,iBAAiB,IAAI,OAAO,IAAI,CAAC,iBAAiB,KAAK,QAAQ,EAAE,CAAC;QACzE,OAAO,IAAI,CAAC,iBAA4C,CAAC;IAC3D,CAAC;IACD,oEAAoE;IACpE,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,EAAE,IAAI,CAAC;IAChE,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,8BAA8B;QAChC,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CACb,uEAAuE,CACxE,CAAC;AACJ,CAAC;AAED,SAAS,cAAc;IACrB,OAAO,IAAI,KAAK,CAAC,EAA2B,EAAE;QAC5C,GAAG,CAAC,OAAO,EAAE,IAAI;YACf,MAAM,IAAI,sBAAsB,CAC9B,gFAAgF,MAAM,CAAC,IAAI,CAAC,4EAA4E,CACzK,CAAC;QACJ,CAAC;KACF,CAA0B,CAAC;AAC9B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAqB,EACrB,IAA0B;IAE1B,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,MAAgB,CAAC,CAAC;IAClD,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC;QACH,qBAAqB,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,WAAW,CAAE,GAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,IAAI,IAAI,CAAC;IACT,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;IACvE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,WAAW,CAAC,4BAA6B,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACrF,CAAC;IAED,MAAM,UAAU,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,UAAU,CAAC,QAA8C,CAAC;IAC3E,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,WAAwD,CAAC;IAClF,MAAM,OAAO,GACX,KAAK,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC;IACtC,MAAM,kBAAkB,GAAG,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IAE5E,MAAM,OAAO,GAAY,MAAM,CAAC,MAAM,CAAC;QACrC,aAAa,EAAE,QAAQ,CAAC,QAAQ;QAChC,OAAO;QACP,kBAAkB;QAClB,KAAK,EAAE,cAAc,EAAE;KACxB,CAAC,CAAC;IACH,YAAY,CAAC,GAAG,CAAC,MAAgB,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 export * from './client.js';
 export { makeCookieJarMiddleware } from './cookies.js';
 export type { paths, components, operations, webhooks } from './generated/paths.js';
+export { connectMootup } from './connect.js';
+export type { ConnectMootupOptions, MCPClientLike, Session, } from './connect.js';
+export { MootupNotOrientedError } from './session.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EACV,oBAAoB,EACpB,aAAa,EACb,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,3 +1,5 @@
 export * from './client.js';
 export { makeCookieJarMiddleware } from './cookies.js';
+export { connectMootup } from './connect.js';
+export { MootupNotOrientedError } from './session.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAM7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,23 @@
+export interface MCPClientLike {
+    callTool(req: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }): Promise<{
+        content?: Array<{
+            type: string;
+            text?: string;
+        }>;
+        structuredContent?: unknown;
+        isError?: boolean;
+    }>;
+}
+export declare class MootupNotOrientedError extends Error {
+    constructor(message?: string);
+}
+export interface Session {
+    readonly participantId: string;
+    readonly spaceId: string | null;
+    readonly orientationSummary: string;
+    readonly tools: Record<string, never>;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,GAAG,OAAO,CAAC;QACV,OAAO,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjD,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC,CAAC;CACJ;AAED,qBAAa,sBAAuB,SAAQ,KAAK;gBAE7C,OAAO,SAA2D;CAKrE;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CACvC"}

package/dist/session.js

@@ -0,0 +1,10 @@
+// AH-g: Session types + error classes for connectMootup.
+// Duck-typed MCPClientLike avoids any dependency on @modelcontextprotocol/sdk
+// (inv 8 — no MCP SDK package in dependencies).
+export class MootupNotOrientedError extends Error {
+    constructor(message = 'Session not yet resolved — await connectMootup() first') {
+        super(message);
+        this.name = 'MootupNotOrientedError';
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,8EAA8E;AAC9E,gDAAgD;AAahD,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YACE,OAAO,GAAG,wDAAwD;QAElE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF"}

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@mootup/moot-sdk",
-  "version": "0.1.0-rc.0",
-  "description": "Typed HTTP client for the convo (mootup) API, generated from OpenAPI 3.1.",
+  "version": "0.2.1",
+  "description": "Typed HTTP client AND MCP harness helpers (connectMootup) for the convo (mootup) API. Zero MCP SDK dependency — duck-typed client interface.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mootup-io/moot-cli-js.git",
+    "directory": "packages/moot-sdk"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -19,11 +24,12 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=18.0.0"
   },
   "scripts": {
     "generate": "openapi-typescript openapi.yaml -o src/generated/paths.ts",
     "sync:oas": "node scripts/sync-oas.mjs",
+    "sync:contract": "node scripts/sync-contract.mjs",
     "build": "npm run generate && tsc -p tsconfig.build.json",
     "test": "vitest run",
     "test:watch": "vitest",

package/src/connect.ts

@@ -0,0 +1,152 @@
+// AH-g: connectMootup — thin SDK helper that calls the shipped convo
+// `orientation` MCP tool via a caller-supplied MCP client, surfaces a
+// typed, frozen Session. Session is memoized per-client (inv 10).
+
+import type { MCPClientLike, Session } from './session.js';
+import { MootupNotOrientedError } from './session.js';
+
+export type { MCPClientLike, Session };
+export { MootupNotOrientedError };
+
+export interface ConnectMootupOptions {
+  baseUrl: string;
+  auth?: string;
+}
+
+// Per-process, per-MCP-client session cache (inv 10).
+const sessionCache = new WeakMap<object, Session>();
+
+// Redaction list — error messages must never surface these (inv 11 / T-2).
+const REDACTION_SUBSTRINGS = ['Bearer ', 'Authorization', 'api_key', 'token'];
+
+function redactError(message: string): string {
+  let out = message;
+  for (const needle of REDACTION_SUBSTRINGS) {
+    if (out.includes(needle)) {
+      out = out.replace(new RegExp(needle, 'gi'), '<redacted>');
+    }
+  }
+  return out;
+}
+
+function resolveAuth(explicit?: string): string {
+  if (explicit) return explicit;
+  const env = globalThis.process?.env ?? {};
+  if (env.MOOTUP_OAUTH_TOKEN) return env.MOOTUP_OAUTH_TOKEN;
+  if (env.MOOTUP_API_KEY) return env.MOOTUP_API_KEY;
+  throw new MootupNotOrientedError(
+    'No auth supplied (kwarg > MOOTUP_OAUTH_TOKEN > MOOTUP_API_KEY > error)',
+  );
+}
+
+const JWT_SHAPE_RE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+
+function validateBaseUrlOrigin(baseUrl: string, token: string): void {
+  // T-1: if token is JWT-shaped (heuristic OAuth detection), compare the
+  // token's second segment (claims) iss URL origin to baseUrl origin.
+  if (!JWT_SHAPE_RE.test(token)) return;
+  const segments = token.split('.');
+  let claims: { iss?: string };
+  try {
+    // base64url-decode the claims segment.
+    const b64 = segments[1].replace(/-/g, '+').replace(/_/g, '/');
+    const pad = b64.length % 4 === 0 ? '' : '='.repeat(4 - (b64.length % 4));
+    const decoded = globalThis.atob
+      ? globalThis.atob(b64 + pad)
+      : Buffer.from(b64 + pad, 'base64').toString('binary');
+    claims = JSON.parse(decoded) as { iss?: string };
+  } catch {
+    return;
+  }
+  if (!claims.iss) return;
+  let issOrigin: string;
+  let baseOrigin: string;
+  try {
+    issOrigin = new URL(claims.iss).origin;
+    baseOrigin = new URL(baseUrl).origin;
+  } catch {
+    throw new Error('base_url or OAuth issuer URL is malformed');
+  }
+  if (issOrigin !== baseOrigin) {
+    throw new Error(
+      `base_url origin (${baseOrigin}) does not match OAuth issuer origin (${issOrigin})`,
+    );
+  }
+}
+
+function extractStructured(resp: {
+  content?: Array<{ type: string; text?: string }>;
+  structuredContent?: unknown;
+  isError?: boolean;
+}): Record<string, unknown> {
+  if (resp.isError) {
+    throw new Error('orientation tool returned isError=true');
+  }
+  if (resp.structuredContent && typeof resp.structuredContent === 'object') {
+    return resp.structuredContent as Record<string, unknown>;
+  }
+  // Fallback: parse the JSON text block if FastMCP emitted only text.
+  const text = resp.content?.find((c) => c.type === 'text')?.text;
+  if (text) {
+    try {
+      return JSON.parse(text) as Record<string, unknown>;
+    } catch {
+      // fall through to error below
+    }
+  }
+  throw new Error(
+    'orientation response missing structuredContent (requires convo ≥AH-g)',
+  );
+}
+
+function makeToolsProxy(): Record<string, never> {
+  return new Proxy({} as Record<string, never>, {
+    get(_target, prop): never {
+      throw new MootupNotOrientedError(
+        `Typed tool accessors are not yet implemented. Tried to access 'session.tools.${String(prop)}'. Use the caller-supplied MCP client directly until typed accessors ship.`,
+      );
+    },
+  }) as Record<string, never>;
+}
+
+export async function connectMootup(
+  client: MCPClientLike,
+  opts: ConnectMootupOptions,
+): Promise<Session> {
+  const cached = sessionCache.get(client as object);
+  if (cached) return cached;
+
+  const token = resolveAuth(opts.auth);
+  try {
+    validateBaseUrlOrigin(opts.baseUrl, token);
+  } catch (err) {
+    throw new Error(redactError((err as Error).message));
+  }
+
+  let resp;
+  try {
+    resp = await client.callTool({ name: 'orientation', arguments: {} });
+  } catch (err) {
+    throw new Error(redactError(`orientation call failed: ${(err as Error).message}`));
+  }
+
+  const structured = extractStructured(resp);
+  const identity = structured.identity as { actor_id?: unknown } | undefined;
+  if (!identity || typeof identity.actor_id !== 'string') {
+    throw new Error('orientation response missing identity.actor_id');
+  }
+  const focus = structured.focus_space as { space_id?: unknown } | null | undefined;
+  const spaceId =
+    focus && typeof focus.space_id === 'string' ? focus.space_id : null;
+  const contextRaw = structured.context;
+  const orientationSummary = typeof contextRaw === 'string' ? contextRaw : '';
+
+  const session: Session = Object.freeze({
+    participantId: identity.actor_id,
+    spaceId,
+    orientationSummary,
+    tools: makeToolsProxy(),
+  });
+  sessionCache.set(client as object, session);
+  return session;
+}

package/src/index.ts

@@ -1,3 +1,10 @@
 export * from './client.js';
 export { makeCookieJarMiddleware } from './cookies.js';
 export type { paths, components, operations, webhooks } from './generated/paths.js';
+export { connectMootup } from './connect.js';
+export type {
+  ConnectMootupOptions,
+  MCPClientLike,
+  Session,
+} from './connect.js';
+export { MootupNotOrientedError } from './session.js';

package/src/session.ts

@@ -0,0 +1,30 @@
+// AH-g: Session types + error classes for connectMootup.
+// Duck-typed MCPClientLike avoids any dependency on @modelcontextprotocol/sdk
+// (inv 8 — no MCP SDK package in dependencies).
+
+export interface MCPClientLike {
+  callTool(req: {
+    name: string;
+    arguments?: Record<string, unknown>;
+  }): Promise<{
+    content?: Array<{ type: string; text?: string }>;
+    structuredContent?: unknown;
+    isError?: boolean;
+  }>;
+}
+
+export class MootupNotOrientedError extends Error {
+  constructor(
+    message = 'Session not yet resolved — await connectMootup() first',
+  ) {
+    super(message);
+    this.name = 'MootupNotOrientedError';
+  }
+}
+
+export interface Session {
+  readonly participantId: string;
+  readonly spaceId: string | null;
+  readonly orientationSummary: string;
+  readonly tools: Record<string, never>;
+}