@reneturcios/decisionscope 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rene Turcios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
+# decisionscope
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+decisionscope gives a tool read-only access to a hosted decision
+record: a system of record for what was actually decided. Before
+acting, a tool can ask the record a natural-language question —
+"Are we still shipping the new onboarding flow?" — and get back
+the current authoritative answer, or an explicit hold when the
+record has no confident answer. A polling caller can also drain
+decisions whose state changed since a cursor. The record only
+answers; it never takes actions in your systems.
+
+decisionscope is a forwarding client. It runs locally as a CLI
+and a stdio MCP server, and forwards each call to the hosted
+endpoint as a JSON-RPC `tools/call` request. The endpoint is named
+by `RITHMO_MCP_URL` and defaults to the hosted service at
+`https://app.rithmo.ai/api/mcp`; a self-hosted deployment exposes
+the same tools and contract at its own address.
+
+## Setup
+
+Every request carries a per-organization service token as a
+Bearer token. The token resolves to exactly one organization,
+must carry the `mcp:read` scope, and every result is scoped to
+that organization. There is no anonymous access.
+
+```bash
+export RITHMO_MCP_TOKEN="<your service token>"
+# Optional; only needed for a self-hosted endpoint:
+export RITHMO_MCP_URL="https://app.rithmo.ai/api/mcp"
+```
+
+Keep the token in a secret store, never in code. With no token
+set, every call fails before any request is sent, with an error
+naming `RITHMO_MCP_TOKEN`.
+
+## Install
+
+```bash
+npx @reneturcios/decisionscope whoami
+```
+
+Or run the container image:
+
+```bash
+docker run -i ghcr.io/cloudcorprecords/decisionscope
+```
+
+The container defaults to the MCP server (see below). Pass CLI
+arguments to use it as a CLI instead, and pass the two environment
+variables above with `-e` so the container can reach your record.
+
+## CLI
+
+```bash
+decisionscope query_decision "Are we still shipping the new onboarding flow?"
+decisionscope query_decision "What did we decide about GitHub integration?" --type decision
+decisionscope query_decision "Who owns the pricing change?" --owner "Priya" --surface jira
+decisionscope list_decision_changes
+decisionscope list_decision_changes --since "0_" --limit 200
+decisionscope whoami
+
+decisionscope --version
+```
+
+Results print as JSON. Exit codes: `0` on success, `1` on an
+operation error (including a missing token), `2` for usage
+errors. Arguments are validated before the token is checked, so a
+malformed call is always a usage error.
+
+## MCP server
+
+One bin serves both faces. The `mcp` subcommand starts a stdio
+MCP server:
+
+```bash
+npx -y @reneturcios/decisionscope mcp
+```
+
+MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "decisionscope": {
+      "command": "npx",
+      "args": ["-y", "@reneturcios/decisionscope", "mcp"],
+      "env": {
+        "RITHMO_MCP_TOKEN": "<your service token>"
+      }
+    }
+  }
+}
+```
+
+Object results are returned as a JSON text block and as
+`structuredContent`, so clients can read
+`res.structuredContent` directly.
+
+### Tools
+
+| Tool | Input | What it returns |
+| --- | --- | --- |
+| `query_decision` | `question` (required); optional `type` (`action_item` \| `follow_up` \| `decision`), `owner`, `area`, `surface` | A result discriminated on `result`: `found`, `found_record`, or `no_record` — see below. |
+| `list_decision_changes` | optional `since` (opaque cursor), optional `limit` (integer 1–200, default 50) | `{ changes, cursor, has_more }` — the changes since the cursor, in `(changed_at, decision_id)` order. |
+| `whoami` | (none) | `{ org_id, scopes }` for the configured token. |
+
+### Reading a `query_decision` result
+
+The `result` field has three variants, and the distinction
+matters:
+
+- `found` — a live answer from the commitment ledger. The answer
+  text is at `answer`, alongside `status`, `lifecycle_state`,
+  `owner` and `source` (both discriminated states, never bare
+  nulls), `decided_at`, `due_at`, `rationale`, `conditions`,
+  `director`, `context`, a `supersedes` chain (newest-first,
+  cycle-guarded, capped at 12 hops), an optional `spine`, and a
+  `confidence` score. Apart from `confidence`, a `found` result
+  for the same decision is byte-identical on every call.
+- `found_record` — a live answer from the subject record. This is
+  an answer, not a refusal. The answer text is at
+  `subject.currentAnswer`, **not** `answer` — and it may be
+  `null`, meaning the subject is on record but there is no answer
+  text to act on.
+- `no_record` — no confident answer. The bare form is just
+  `{ "result": "no_record" }`; a typed form adds a `record`
+  explaining why the answer is held (`closed`, `no_record`, or
+  `not_observed` when the asked-about surface is one the record
+  does not observe). A `premise_check`, when present, always has
+  `safe_to_proceed: false`. Never proceed on a `no_record`.
+
+Gate on a usable answer, not on the variant name:
+
+```js
+const r = res.structuredContent;
+const answer =
+  r.result === 'found'        ? r.answer :
+  r.result === 'found_record' ? r.subject.currentAnswer :
+  null;
+if (answer != null && String(answer).trim() !== '') { /* act */ }
+else { /* hold — no answer to act on */ }
+```
+
+One special case: a `no_record` whose `record.reason` starts
+with `record_unavailable:` means the record itself could not be
+read (a transient failure). That is not "we decided no" — hold
+and retry.
+
+### Draining changes
+
+`list_decision_changes` is built for a polling trigger:
+
+- First call (no `since`): returns no changes and the current
+  head cursor. You start from now; history is not replayed. Pass
+  `since: "0_"` to backfill from the start instead.
+- `has_more` means the page was full (`changes.length ===
+  limit`). It can be true on an exactly-full final page, so the
+  next call may legitimately return zero changes — that is how
+  the drain terminates, not an error.
+- When a page returns no rows, the cursor is echoed back
+  unchanged, so re-polling with it is safe and idempotent.
+- Each change carries the same record core as a `found` result,
+  plus `changed_at` — but never `supersedes`, `spine`, or
+  `confidence`. Its `status` is wider: reversals appear as
+  `dropped` or `superseded`, values a `found` result never
+  returns.
+
+## Development
+
+```bash
+npm install
+npm run build   # tsc -> dist/
+npm test        # node test runner over test/*.test.ts, no network (fake fetch only)
+npm run dev     # run the CLI from source via tsx
+```
+
+## License
+
+MIT — see `LICENSE`.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * decisionscope CLI.
+ *
+ *   decisionscope query_decision <question> [--type <t>] [--owner <o>] [--area <a>] [--surface <s>]
+ *   decisionscope query_decision --question <question> [--type <t>] [--owner <o>] [--area <a>] [--surface <s>]
+ *   decisionscope list_decision_changes [--since <cursor>] [--limit <n>]
+ *   decisionscope whoami
+ *   decisionscope mcp
+ *   decisionscope --version
+ *
+ * Endpoint from RITHMO_MCP_URL (default https://app.rithmo.ai/api/mcp);
+ * service token from RITHMO_MCP_TOKEN, sent as a Bearer token.
+ * Argument validation runs before any credential check.
+ * Exit codes: 0 success, 1 operation error, 2 usage error.
+ */
+import { buildForwardArguments, callDecisionscopeTool, formatPayload, TOKEN_ENV, URL_ENV, VERSION, } from "./decisionscope.js";
+function usage() {
+    console.error(`Usage:
+  decisionscope query_decision <question> [--type <action_item|follow_up|decision>] [--owner <name>] [--area <hint>] [--surface <system>]
+  decisionscope list_decision_changes [--since <cursor>] [--limit <1-200>]
+  decisionscope whoami
+  decisionscope mcp
+  decisionscope --version
+
+Endpoint: ${URL_ENV} (default https://app.rithmo.ai/api/mcp).
+Token: ${TOKEN_ENV} (per-organization service token, scope mcp:read).`);
+    process.exit(2);
+}
+/** Parse "--flag value" pairs; returns null on a dangling flag. */
+function flagMap(rest) {
+    const map = new Map();
+    for (let i = 0; i < rest.length; i += 2) {
+        const key = rest[i];
+        if (!key.startsWith("--") || i + 1 >= rest.length)
+            return null;
+        map.set(key, rest[i + 1]);
+    }
+    return map;
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    if (cmd === "--version" || cmd === "-v") {
+        console.log(VERSION);
+        return;
+    }
+    if (cmd === "mcp") {
+        await import("./mcp.js");
+        return;
+    }
+    if (!cmd)
+        usage();
+    const known = ["query_decision", "list_decision_changes", "whoami"];
+    if (!known.includes(cmd))
+        usage();
+    // Build and validate arguments BEFORE any credential check:
+    // invalid arguments are a usage error (exit 2), never a token error.
+    let args = {};
+    try {
+        if (cmd === "query_decision") {
+            const positional = [];
+            const flagArgs = [];
+            for (let i = 0; i < rest.length; i++) {
+                if (rest[i].startsWith("--")) {
+                    flagArgs.push(rest[i], rest[i + 1] ?? "");
+                    i++;
+                }
+                else {
+                    positional.push(rest[i]);
+                }
+            }
+            if (positional.length > 1)
+                usage();
+            const flags = flagMap(flagArgs);
+            if (!flags)
+                usage();
+            const allowed = new Set(["--question", "--type", "--owner", "--area", "--surface"]);
+            for (const key of flags.keys())
+                if (!allowed.has(key))
+                    usage();
+            const question = flags.get("--question") ?? positional[0];
+            if (question !== undefined)
+                args.question = question;
+            if (flags.has("--type"))
+                args.type = flags.get("--type");
+            if (flags.has("--owner"))
+                args.owner = flags.get("--owner");
+            if (flags.has("--area"))
+                args.area = flags.get("--area");
+            if (flags.has("--surface"))
+                args.surface = flags.get("--surface");
+        }
+        else if (cmd === "list_decision_changes") {
+            const flags = flagMap(rest);
+            if (!flags)
+                usage();
+            const allowed = new Set(["--since", "--limit"]);
+            for (const key of flags.keys())
+                if (!allowed.has(key))
+                    usage();
+            if (flags.has("--since"))
+                args.since = flags.get("--since");
+            if (flags.has("--limit")) {
+                const raw = flags.get("--limit");
+                if (!/^-?\d+$/.test(raw))
+                    usage();
+                args.limit = Number(raw);
+            }
+        }
+        else {
+            if (rest.length)
+                usage();
+        }
+        args = buildForwardArguments(cmd, args);
+    }
+    catch {
+        usage();
+    }
+    const fetchFn = globalThis.fetch;
+    try {
+        const out = await callDecisionscopeTool({ fetchFn }, cmd, args);
+        console.log(formatPayload(out));
+    }
+    catch (err) {
+        console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+}
+void main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/decisionscope.d.ts

@@ -0,0 +1,64 @@
+/**
+ * decisionscope core: a forwarding client for a hosted, read-only
+ * decision record.
+ *
+ * The upstream server is a hosted MCP endpoint. Each tool call here
+ * becomes exactly one JSON-RPC `tools/call` POST to the endpoint
+ * named by RITHMO_MCP_URL (default https://app.rithmo.ai/api/mcp),
+ * carrying the per-organization service token from RITHMO_MCP_TOKEN
+ * as `Authorization: Bearer <token>`. The token must carry the
+ * `mcp:read` scope; every result is scoped to the token's
+ * organization. There is no anonymous access.
+ *
+ * Rules honoured here, from the documented contract:
+ * - Argument validation runs before the credential check, and the
+ *   credential check runs before any request: a missing or blank
+ *   token fails with an error naming RITHMO_MCP_TOKEN and no
+ *   request is ever sent.
+ * - `query_decision` returns the upstream payload verbatim. Its
+ *   `result` field discriminates "found" (answer at `answer`),
+ *   "found_record" (answer at `subject.currentAnswer`, which may
+ *   be null), and "no_record" (a held answer, never an error).
+ *   Callers must gate on a usable answer, not on the variant name.
+ * - `list_decision_changes` validates `limit` as an integer in
+ *   1-200 and rejects out-of-range or non-integer values instead
+ *   of clamping; the `since` cursor is opaque and passed through
+ *   unchanged. When the caller omits `limit`, it is not sent, so
+ *   the upstream default (50) applies; the same holds for `since`
+ *   (omit on the first call to start from now; "0_" backfills).
+ * - `whoami` takes no arguments and returns `{ org_id, scopes }`.
+ *
+ * The upstream reply may be a plain JSON-RPC body or an SSE stream
+ * (`data:` lines); both are unwrapped. A result's
+ * `structuredContent` wins when present; otherwise a JSON text
+ * content block is parsed; otherwise the raw result is returned.
+ * HTTP failures and JSON-RPC errors are thrown as errors — the
+ * record's own `no_record` outcome is a result, not an error.
+ *
+ * All HTTP goes through an injected FetchFn so the request
+ * shaping is fully testable offline with fake responses.
+ */
+import type { CallDeps, ListDecisionChangesArgs, QueryDecisionArgs } from "./types.js";
+export declare const VERSION = "0.1.0";
+export declare const TOKEN_ENV = "RITHMO_MCP_TOKEN";
+export declare const URL_ENV = "RITHMO_MCP_URL";
+export declare const DEFAULT_BASE_URL = "https://app.rithmo.ai/api/mcp";
+export declare const REQUIRED_SCOPE = "mcp:read";
+export declare const TOOL_NAMES: readonly ["query_decision", "list_decision_changes", "whoami"];
+export type ToolName = (typeof TOOL_NAMES)[number];
+/** Read the service token out of an environment map. */
+export declare function resolveToken(env?: Record<string, string | undefined>): string | undefined;
+/** Resolve the endpoint: explicit value, then RITHMO_MCP_URL, then the hosted default. */
+export declare function resolveBaseUrl(explicit?: string, env?: Record<string, string | undefined>): string;
+/** Validate query_decision arguments and shape the forwarded arguments. */
+export declare function buildQueryDecisionArgs(args: Record<string, unknown>): QueryDecisionArgs;
+/** Validate list_decision_changes arguments and shape the forwarded arguments. */
+export declare function buildListDecisionChangesArgs(args: Record<string, unknown>): ListDecisionChangesArgs;
+/** Validate whoami arguments (none are accepted) and shape the forwarded arguments. */
+export declare function buildWhoamiArgs(args: Record<string, unknown>): Record<string, never>;
+/** Validate one tool's arguments and return the arguments to forward. */
+export declare function buildForwardArguments(tool: string, args: Record<string, unknown>): Record<string, unknown>;
+/** Generic entry point used by the MCP server and the CLI. */
+export declare function callDecisionscopeTool(deps: CallDeps, tool: string, args: Record<string, unknown>): Promise<unknown>;
+/** Render a payload as the JSON text block MCP clients show. */
+export declare function formatPayload(payload: unknown): string;

package/dist/decisionscope.js

@@ -0,0 +1,206 @@
+export const VERSION = "0.1.0";
+export const TOKEN_ENV = "RITHMO_MCP_TOKEN";
+export const URL_ENV = "RITHMO_MCP_URL";
+export const DEFAULT_BASE_URL = "https://app.rithmo.ai/api/mcp";
+export const REQUIRED_SCOPE = "mcp:read";
+export const TOOL_NAMES = [
+    "query_decision",
+    "list_decision_changes",
+    "whoami",
+];
+const DECISION_TYPES = ["action_item", "follow_up", "decision"];
+/** Read the service token out of an environment map. */
+export function resolveToken(env = process.env) {
+    const raw = typeof env[TOKEN_ENV] === "string" ? env[TOKEN_ENV].trim() : "";
+    return raw ? raw : undefined;
+}
+/** Resolve the endpoint: explicit value, then RITHMO_MCP_URL, then the hosted default. */
+export function resolveBaseUrl(explicit, env = process.env) {
+    const raw = (explicit ?? env[URL_ENV] ?? DEFAULT_BASE_URL).trim();
+    return raw.replace(/\/+$/, "") || DEFAULT_BASE_URL;
+}
+function reqString(args, field) {
+    const v = args[field];
+    if (typeof v !== "string" || !v.trim()) {
+        throw new Error(`${field} must be a non-empty string`);
+    }
+    return v;
+}
+function optString(args, field) {
+    const v = args[field];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "string" || !v.trim()) {
+        throw new Error(`${field} must be a non-empty string when provided`);
+    }
+    return v;
+}
+/** Validate query_decision arguments and shape the forwarded arguments. */
+export function buildQueryDecisionArgs(args) {
+    const out = { question: reqString(args, "question") };
+    const type = args.type;
+    if (type !== undefined) {
+        if (typeof type !== "string" || !DECISION_TYPES.includes(type)) {
+            throw new Error(`type must be one of ${DECISION_TYPES.join(", ")} when provided`);
+        }
+        out.type = type;
+    }
+    const owner = optString(args, "owner");
+    if (owner !== undefined)
+        out.owner = owner;
+    const area = optString(args, "area");
+    if (area !== undefined)
+        out.area = area;
+    const surface = optString(args, "surface");
+    if (surface !== undefined)
+        out.surface = surface;
+    return out;
+}
+/** Validate list_decision_changes arguments and shape the forwarded arguments. */
+export function buildListDecisionChangesArgs(args) {
+    const out = {};
+    const since = args.since;
+    if (since !== undefined) {
+        if (typeof since !== "string" || !since) {
+            throw new Error("since must be a non-empty string when provided");
+        }
+        out.since = since;
+    }
+    const limit = args.limit;
+    if (limit !== undefined) {
+        if (typeof limit !== "number" ||
+            !Number.isInteger(limit) ||
+            limit < 1 ||
+            limit > 200) {
+            throw new Error("limit must be an integer between 1 and 200");
+        }
+        out.limit = limit;
+    }
+    return out;
+}
+/** Validate whoami arguments (none are accepted) and shape the forwarded arguments. */
+export function buildWhoamiArgs(args) {
+    if (Object.keys(args ?? {}).length > 0) {
+        throw new Error("whoami takes no arguments");
+    }
+    return {};
+}
+/** Validate one tool's arguments and return the arguments to forward. */
+export function buildForwardArguments(tool, args) {
+    const a = args ?? {};
+    switch (tool) {
+        case "query_decision":
+            return { ...buildQueryDecisionArgs(a) };
+        case "list_decision_changes":
+            return { ...buildListDecisionChangesArgs(a) };
+        case "whoami":
+            return { ...buildWhoamiArgs(a) };
+        default:
+            throw new Error(`Unknown tool: ${tool}`);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Parse a response body that may be plain JSON or an SSE stream of JSON-RPC messages. */
+function parseRpcBody(bodyText) {
+    const trimmed = bodyText.trim();
+    if (!trimmed)
+        throw new Error("upstream returned an empty response body");
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (isRecord(parsed))
+            return parsed;
+        throw new Error("upstream returned a non-object JSON response");
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith("upstream returned"))
+            throw err;
+        // Fall through to SSE parsing.
+    }
+    let last;
+    for (const line of trimmed.split(/\r?\n/)) {
+        const m = line.match(/^data:\s*(.*)$/);
+        if (!m || !m[1].trim())
+            continue;
+        try {
+            const parsed = JSON.parse(m[1]);
+            if (isRecord(parsed))
+                last = parsed;
+        }
+        catch {
+            // A non-JSON data line is not an RPC message; keep scanning.
+        }
+    }
+    if (last)
+        return last;
+    throw new Error("upstream response was neither JSON nor an SSE stream of JSON-RPC messages");
+}
+/** Extract the tool payload from a JSON-RPC response envelope. */
+function unwrapResult(rpc, url) {
+    if (isRecord(rpc.error)) {
+        const message = typeof rpc.error.message === "string" ? rpc.error.message : "unknown upstream error";
+        throw new Error(`upstream tools/call to ${url} failed: ${message}`);
+    }
+    const result = rpc.result;
+    if (!isRecord(result))
+        return result;
+    if (result.structuredContent !== undefined)
+        return result.structuredContent;
+    if (Array.isArray(result.content)) {
+        for (const block of result.content) {
+            if (isRecord(block) && block.type === "text" && typeof block.text === "string") {
+                try {
+                    return JSON.parse(block.text);
+                }
+                catch {
+                    return block.text;
+                }
+            }
+        }
+    }
+    return result;
+}
+/** Generic entry point used by the MCP server and the CLI. */
+export async function callDecisionscopeTool(deps, tool, args) {
+    // Argument validation first, before any credential check.
+    const forwardArgs = buildForwardArguments(tool, args ?? {});
+    const env = deps.env ?? process.env;
+    const token = (typeof deps.token === "string" ? deps.token.trim() : "") || resolveToken(env);
+    if (!token) {
+        throw new Error(`${TOKEN_ENV} is not set: a per-organization service token with the ${REQUIRED_SCOPE} scope is required (sent as a Bearer token). No request was sent.`);
+    }
+    const url = resolveBaseUrl(deps.baseUrl, env);
+    const body = JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: tool, arguments: forwardArgs },
+    });
+    let response;
+    try {
+        response = await deps.fetchFn(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json, text/event-stream",
+                Authorization: `Bearer ${token}`,
+            },
+            body,
+        });
+    }
+    catch (err) {
+        throw new Error(`request to ${url} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const bodyText = await response.text();
+    if (!response.ok) {
+        const detail = bodyText.trim() ? `: ${bodyText.trim().slice(0, 200)}` : "";
+        throw new Error(`upstream ${url} returned HTTP ${response.status}${detail}`);
+    }
+    return unwrapResult(parseRpcBody(bodyText), url);
+}
+/** Render a payload as the JSON text block MCP clients show. */
+export function formatPayload(payload) {
+    return typeof payload === "string" ? payload : JSON.stringify(payload, null, 2);
+}
+//# sourceMappingURL=decisionscope.js.map

package/dist/decisionscope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisionscope.js","sourceRoot":"","sources":["../src/decisionscope.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./decisionscope.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./decisionscope.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC"}

package/dist/mcp.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp.js

@@ -0,0 +1,138 @@
+/**
+ * decisionscope MCP server. Tools: query_decision,
+ * list_decision_changes, whoami.
+ *
+ * Why the low-level Server instead of McpServer: the high-level
+ * helper converts zod schemas to JSON Schema and injects keys that
+ * are not in this tool's public spec ("$schema" and
+ * "additionalProperties"), which breaks exact tool-list/schema
+ * parity with the spec. This file serves tools/list with the
+ * spec's exact input schemas as explicit literals, while zod still
+ * validates every tools/call argument set.
+ *
+ * This server is a forwarding client: every call is forwarded to
+ * the hosted endpoint named by RITHMO_MCP_URL (default
+ * https://app.rithmo.ai/api/mcp) with the RITHMO_MCP_TOKEN service
+ * token as a Bearer token. A missing token is an isError result
+ * naming RITHMO_MCP_TOKEN, returned before any request is sent.
+ * Object payloads are returned both as a JSON text block and as
+ * structuredContent, matching how the documented contract is
+ * consumed (`res.structuredContent`).
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { callDecisionscopeTool, formatPayload, resolveToken, VERSION, } from "./decisionscope.js";
+const QueryDecision = z.object({
+    question: z.string(),
+    type: z.enum(["action_item", "follow_up", "decision"]).optional(),
+    owner: z.string().optional(),
+    area: z.string().optional(),
+    surface: z.string().optional(),
+});
+const ListDecisionChanges = z.object({
+    since: z.string().optional(),
+    limit: z.number().int().min(1).max(200).optional(),
+});
+const Whoami = z.object({});
+const TOOLS = [
+    {
+        name: "query_decision",
+        description: "Look up the current authoritative decision for a natural-language question. Returns a found, found_record, or no_record result.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                question: { type: "string", description: "The natural-language question to look up a decision for." },
+                type: {
+                    type: "string",
+                    enum: ["action_item", "follow_up", "decision"],
+                    description: "Restrict to records of this type: action item, follow-up, or decision.",
+                },
+                owner: { type: "string", description: "Restrict to records owned by this person." },
+                area: { type: "string", description: "Restrict to records in this area." },
+                surface: { type: "string", description: "Restrict to records from this surface." },
+            },
+            required: ["question"],
+        },
+    },
+    {
+        name: "list_decision_changes",
+        description: "List decisions whose state changed since an opaque cursor, for polling. Omit since to start from now; pass \"0_\" to backfill from the start.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                since: { type: "string", description: "Opaque cursor from a previous call; omit to start from now, or pass \"0_\" to backfill from the start." },
+                limit: { type: "integer", minimum: 1, maximum: 200, default: 50, description: "Maximum number of changes to return." },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "whoami",
+        description: "Return the organization and scopes for the configured service token: { org_id, scopes }.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+];
+const SCHEMAS = {
+    query_decision: QueryDecision,
+    list_decision_changes: ListDecisionChanges,
+    whoami: Whoami,
+};
+function resultPayload(value) {
+    const base = {
+        content: [
+            {
+                type: "text",
+                text: typeof value === "string" ? value : formatPayload(value),
+            },
+        ],
+    };
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return {
+            ...base,
+            structuredContent: value,
+        };
+    }
+    return base;
+}
+function errorResult(err) {
+    return {
+        content: [
+            { type: "text", text: err instanceof Error ? err.message : String(err) },
+        ],
+        isError: true,
+    };
+}
+const server = new Server({ name: "decisionscope", version: VERSION }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const schema = SCHEMAS[name];
+    if (!schema)
+        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+    const fetchFn = globalThis.fetch;
+    try {
+        const parsed = schema.parse(args ?? {});
+        const out = await callDecisionscopeTool({
+            fetchFn,
+            token: resolveToken(process.env),
+            baseUrl: process.env.RITHMO_MCP_URL,
+        }, name, parsed);
+        return resultPayload(out);
+    }
+    catch (err) {
+        if (err instanceof McpError)
+            throw err;
+        return errorResult(err);
+    }
+});
+async function main() {
+    await server.connect(new StdioServerTransport());
+}
+void main();
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * decisionscope types.
+ *
+ * The three tools are thin, typed views over a hosted, read-only
+ * decision record. Argument shapes follow the documented Input
+ * tables exactly. Result payloads are passed through verbatim from
+ * the upstream server, so the result types describe the documented
+ * variants without narrowing away fields the record may carry.
+ */
+/** Restrict a decision query to one record type. */
+export type DecisionType = "action_item" | "follow_up" | "decision";
+/** Arguments for query_decision. */
+export interface QueryDecisionArgs {
+    question: string;
+    type?: DecisionType;
+    owner?: string;
+    area?: string;
+    surface?: string;
+}
+/** Arguments for list_decision_changes. */
+export interface ListDecisionChangesArgs {
+    /** Opaque cursor from a prior call; omit to start from now, "0_" to backfill. */
+    since?: string;
+    /** Page size, integer 1-200; the upstream default is 50. */
+    limit?: number;
+}
+/** Owner as a discriminated state, never a bare null. */
+export type DecisionOwner = {
+    state: "owned";
+    name: string;
+    user_id: string;
+} | {
+    state: "unowned";
+};
+/** Source as a discriminated state, never a bare null. */
+export type DecisionSource = {
+    state: "resolved";
+    system: string;
+    ref: string;
+    url: string;
+} | {
+    state: "unresolved";
+};
+/**
+ * A query_decision result: a discriminated union on `result`
+ * ("found" | "found_record" | "no_record"). The payload is kept
+ * open because each variant carries its own documented fields and
+ * the record is returned verbatim.
+ */
+export type QueryDecisionResult = {
+    result: string;
+} & Record<string, unknown>;
+/** One entry of a list_decision_changes page. */
+export type DecisionChange = Record<string, unknown>;
+/** A list_decision_changes page: changes plus the drain cursor. */
+export interface ListDecisionChangesResult {
+    changes: DecisionChange[];
+    cursor: string;
+    has_more: boolean;
+}
+/** whoami result: the organization the token resolves to, and its scopes. */
+export interface WhoamiResult {
+    org_id: string;
+    scopes: string[];
+}
+/** Minimal HTTP response surface so tests can inject fixtures. */
+export interface HttpResponse {
+    ok: boolean;
+    status: number;
+    statusText?: string;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+export type FetchFn = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    redirect?: string;
+}) => Promise<HttpResponse>;
+/** Dependencies for a tool call; fetch is injectable for tests. */
+export interface CallDeps {
+    fetchFn: FetchFn;
+    /** Service token; falls back to RITHMO_MCP_TOKEN in `env`. */
+    token?: string;
+    /** Endpoint override; falls back to RITHMO_MCP_URL in `env`, then the default. */
+    baseUrl?: string;
+    /** Environment map used for token / URL resolution. Defaults to process.env. */
+    env?: Record<string, string | undefined>;
+}

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * decisionscope types.
+ *
+ * The three tools are thin, typed views over a hosted, read-only
+ * decision record. Argument shapes follow the documented Input
+ * tables exactly. Result payloads are passed through verbatim from
+ * the upstream server, so the result types describe the documented
+ * variants without narrowing away fields the record may carry.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/package.json

@@ -1,6 +1 @@
-{
-  "name": "@reneturcios/decisionscope",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{"bin":{"decisionscope":"dist/cli.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1","zod":"^4"},"description":"Read-only access to a hosted decision record: query the authoritative decision for a question, drain decision changes since a cursor, and verify your service token. One bin serves a small CLI and a stdio MCP server that forwards to the hosted endpoint.","devDependencies":{"@types/node":"^20","tsx":"^4","typescript":"^5"},"engines":{"node":">=20"},"files":["dist","server.json"],"homepage":"https://github.com/CloudCorpRecords/decisionscope#readme","license":"MIT","mcpName":"io.github.CloudCorpRecords/decisionscope","name":"@reneturcios/decisionscope","private":false,"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/CloudCorpRecords/decisionscope.git"},"scripts":{"build":"tsc","dev":"tsx src/cli.ts","test":"tsx --test test/*.test.ts"},"type":"module","version":"0.1.0"}

package/server.json

@@ -0,0 +1 @@
+{"$schema":"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json","description":"Read-only decision record: query decisions, drain decision changes, verify token.","name":"io.github.CloudCorpRecords/decisionscope","packages":[{"identifier":"@reneturcios/decisionscope","packageArguments":[{"type":"positional","value":"mcp"}],"registryBaseUrl":"https://registry.npmjs.org","registryType":"npm","runtimeHint":"npx","transport":{"type":"stdio"},"version":"0.1.0"},{"identifier":"ghcr.io/cloudcorprecords/decisionscope:0.1.0","packageArguments":[{"type":"positional","value":"mcp"}],"registryType":"oci","runtimeArguments":[{"name":"--rm","type":"named"},{"name":"-i","type":"named"}],"runtimeHint":"docker","transport":{"type":"stdio"}}],"repository":{"source":"github","url":"https://github.com/CloudCorpRecords/decisionscope"},"version":"0.1.0"}