@atrib/daemon 0.1.0

package/dist/index.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * atribd: the local daemon for atrib's seven cognitive primitives.
+ *
+ * One host-owned process mounts the seven primitive MCP servers in process
+ * and serves their fifteen physical tools as thin aliases over two internal
+ * handlers (write, read). Transports: stateless Streamable HTTP (the
+ * recommended daemon topology), direct stdio (in-process), and a
+ * stdio-to-HTTP proxy shim for startup-spawn harnesses.
+ *
+ * Signed records are byte-identical to the standalone per-primitive
+ * binaries: the daemon calls the same handler code paths with the same
+ * `_local.producer` sidecar labels, and never reimplements chain-root
+ * selection (D067; `resolveChainRoot` in @atrib/mcp stays the single
+ * source of truth).
+ */
+import { pathToFileURL } from 'node:url';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { bindAtribdHttpHost, httpEndpoint, normalizeMcpPath, DEFAULT_HTTP_HOST, DEFAULT_HTTP_PATH, DEFAULT_HTTP_PORT, DEFAULT_TOOLS_LIST_TTL_MS, } from './http-host.js';
+import { createAtribdHttpProxyRuntime, createAtribdRuntime } from './stdio.js';
+import { DEFAULT_TOOL_TIMEOUT_MS } from './backend.js';
+export { createAtribdBackend, callWithToolTimeout, readPackageVersion, runtimeContractsDegraded, toolCallDiagnosticsDegraded, writeSerializationKey, ContextWriteLocks, logDaemonEvent, errorMessage, PRIMITIVE_SPECS, WRITE_TOOL_NAMES, DEFAULT_TOOL_TIMEOUT_MS, } from './backend.js';
+export { applyHttpContextPolicy, MISSING_CONTEXT_ERROR_TEXT, } from './context-policy.js';
+export { createSessionSdkStatelessAdapter, } from './transport-adapter.js';
+export { bindAtribdHttpHost, createAtribdServer, routingHeaderMismatch, httpEndpoint, normalizeMcpPath, healthPathFor, DEFAULT_HTTP_HOST, DEFAULT_HTTP_PORT, DEFAULT_HTTP_PATH, DEFAULT_TOOLS_LIST_TTL_MS, } from './http-host.js';
+export { createAtribdRuntime, createAtribdHttpProxyRuntime, } from './stdio.js';
+function envString(...names) {
+    for (const name of names) {
+        const value = process.env[name];
+        if (value !== undefined && value !== '')
+            return value;
+    }
+    return undefined;
+}
+const TRUE_ENV_VALUES = new Set(['1', 'true', 'yes', 'on']);
+function envFlag(...names) {
+    const raw = envString(...names);
+    return raw !== undefined && TRUE_ENV_VALUES.has(raw.trim().toLowerCase());
+}
+function requireArg(argv, index, flag) {
+    const value = argv[index];
+    if (value === undefined)
+        throw new Error(`${flag} requires a value`);
+    return value;
+}
+function parsePort(raw) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 0 || n > 65535) {
+        throw new Error('--port must be an integer from 0 to 65535');
+    }
+    return n;
+}
+function parseOptionalPort(raw) {
+    if (raw === undefined || raw === '')
+        return undefined;
+    return parsePort(raw);
+}
+function parsePositiveInt(raw, name) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return n;
+}
+function parseOptionalPositiveInt(raw, name) {
+    if (raw === undefined || raw === '')
+        return undefined;
+    return parsePositiveInt(raw, name);
+}
+function normalizeHttpEndpoint(raw, flag) {
+    try {
+        const url = new URL(raw);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            throw new Error('unsupported protocol');
+        }
+        return url.toString();
+    }
+    catch {
+        throw new Error(`${flag} must be an absolute HTTP URL`);
+    }
+}
+function deprecatedSessionIdleNotice(source) {
+    process.stderr.write(`atribd: ${source} is ignored; the stateless daemon has no HTTP sessions to expire\n`);
+}
+export function parseCliOptions(argv) {
+    const options = {
+        transport: 'stdio',
+        host: envString('ATRIBD_HTTP_HOST', 'ATRIB_PRIMITIVES_HTTP_HOST') ?? DEFAULT_HTTP_HOST,
+        port: parseOptionalPort(envString('ATRIBD_HTTP_PORT', 'ATRIB_PRIMITIVES_HTTP_PORT')) ??
+            DEFAULT_HTTP_PORT,
+        path: envString('ATRIBD_HTTP_PATH', 'ATRIB_PRIMITIVES_HTTP_PATH') ?? DEFAULT_HTTP_PATH,
+        endpoint: envString('ATRIBD_HTTP_ENDPOINT', 'ATRIB_PRIMITIVES_HTTP_ENDPOINT') ??
+            httpEndpoint(DEFAULT_HTTP_HOST, DEFAULT_HTTP_PORT, DEFAULT_HTTP_PATH),
+        json: false,
+        toolTimeoutMs: parseOptionalPositiveInt(envString('ATRIBD_TOOL_TIMEOUT_MS', 'ATRIB_PRIMITIVES_TOOL_TIMEOUT_MS'), 'ATRIBD_TOOL_TIMEOUT_MS') ?? DEFAULT_TOOL_TIMEOUT_MS,
+        toolsListTtlMs: parseOptionalPositiveInt(envString('ATRIBD_TOOLS_LIST_TTL_MS'), 'ATRIBD_TOOLS_LIST_TTL_MS') ??
+            DEFAULT_TOOLS_LIST_TTL_MS,
+        ambientContext: envFlag('ATRIBD_AMBIENT_CONTEXT'),
+        help: false,
+    };
+    // Deprecated session-era configuration: honored as a no-op with a
+    // one-line stderr notice, never a fatal error (§5.8 posture toward
+    // configuration drift).
+    if (envString('ATRIB_PRIMITIVES_SESSION_IDLE_MS') !== undefined) {
+        deprecatedSessionIdleNotice('ATRIB_PRIMITIVES_SESSION_IDLE_MS');
+    }
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--help' || arg === '-h') {
+            options.help = true;
+        }
+        else if (arg === '--http') {
+            options.transport = 'streamable-http';
+        }
+        else if (arg === '--transport') {
+            const value = requireArg(argv, ++i, '--transport');
+            if (value !== 'stdio' && value !== 'streamable-http' && value !== 'stdio-http-proxy') {
+                throw new Error('--transport must be stdio, streamable-http, or stdio-http-proxy');
+            }
+            options.transport = value;
+        }
+        else if (arg === '--endpoint') {
+            options.endpoint = requireArg(argv, ++i, '--endpoint');
+        }
+        else if (arg === '--host') {
+            options.host = requireArg(argv, ++i, '--host');
+        }
+        else if (arg === '--port') {
+            options.port = parsePort(requireArg(argv, ++i, '--port'));
+        }
+        else if (arg === '--path') {
+            options.path = requireArg(argv, ++i, '--path');
+        }
+        else if (arg === '--json') {
+            options.json = true;
+        }
+        else if (arg === '--tool-timeout-ms') {
+            options.toolTimeoutMs = parsePositiveInt(requireArg(argv, ++i, '--tool-timeout-ms'), '--tool-timeout-ms');
+        }
+        else if (arg === '--tools-list-ttl-ms') {
+            options.toolsListTtlMs = parsePositiveInt(requireArg(argv, ++i, '--tools-list-ttl-ms'), '--tools-list-ttl-ms');
+        }
+        else if (arg === '--ambient-context') {
+            options.ambientContext = true;
+        }
+        else if (arg === '--session-idle-ms') {
+            requireArg(argv, ++i, '--session-idle-ms');
+            deprecatedSessionIdleNotice('--session-idle-ms');
+        }
+        else {
+            throw new Error(`unknown argument: ${arg}`);
+        }
+    }
+    options.path = normalizeMcpPath(options.path);
+    options.endpoint = normalizeHttpEndpoint(options.endpoint, '--endpoint');
+    return options;
+}
+function usage() {
+    return `Usage:
+  atribd [--transport stdio]
+  atribd --transport streamable-http [--host 127.0.0.1] [--port 8796] [--path /mcp]
+  atribd --transport stdio-http-proxy --endpoint http://127.0.0.1:8796/mcp
+
+Options:
+  --http                         Alias for --transport streamable-http.
+  --transport <mode>             stdio, streamable-http, or stdio-http-proxy. Defaults to stdio.
+  --endpoint <url>               HTTP MCP endpoint for stdio-http-proxy mode.
+  --host <host>                  HTTP bind host. Defaults to 127.0.0.1.
+  --port <port>                  HTTP bind port. Defaults to 8796. Use 0 for ephemeral.
+  --path <path>                  HTTP MCP path. Defaults to /mcp.
+  --tool-timeout-ms <ms>         Bound each primitive tool call. Defaults to 45000.
+  --tools-list-ttl-ms <ms>       SEP-2549 freshness hint on tools/list. Defaults to 24 hours.
+  --ambient-context              Opt the HTTP surface back into ambient context discovery
+                                 (D078/D083). Default is explicit-required.
+  --session-idle-ms <ms>         Deprecated; ignored (the stateless daemon has no sessions).
+  --json                         Print a JSON ready line in HTTP mode.
+  --help                         Print this help.
+`;
+}
+async function main() {
+    const options = parseCliOptions(process.argv.slice(2));
+    if (options.help) {
+        process.stdout.write(usage());
+        return;
+    }
+    if (options.transport === 'streamable-http') {
+        const host = await bindAtribdHttpHost({
+            host: options.host,
+            port: options.port,
+            path: options.path,
+            jsonReady: options.json,
+            toolTimeoutMs: options.toolTimeoutMs,
+            toolsListTtlMs: options.toolsListTtlMs,
+            ambientContext: options.ambientContext,
+        });
+        const shutdown = async () => {
+            try {
+                await host.close();
+            }
+            finally {
+                process.exit(0);
+            }
+        };
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
+        if (!options.json) {
+            process.stderr.write(`atribd: listening at ${host.endpoint}\n`);
+        }
+        return;
+    }
+    const runtime = options.transport === 'stdio-http-proxy'
+        ? await createAtribdHttpProxyRuntime(options.endpoint, {
+            toolTimeoutMs: options.toolTimeoutMs,
+        })
+        : await createAtribdRuntime({
+            toolTimeoutMs: options.toolTimeoutMs,
+            toolsListTtlMs: options.toolsListTtlMs,
+        });
+    const shutdown = async () => {
+        try {
+            await runtime.close();
+        }
+        finally {
+            process.exit(0);
+        }
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+    const transport = new StdioServerTransport();
+    await runtime.server.connect(transport);
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().catch((e) => {
+        process.stderr.write(`atribd: fatal ${e instanceof Error ? (e.stack ?? e.message) : String(e)}\n`);
+        process.exit(1);
+    });
+}

package/dist/stdio.d.ts

@@ -0,0 +1,22 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type Tool } from '@modelcontextprotocol/sdk/types.js';
+export interface AtribdRuntime {
+    server: Server;
+    tools: Tool[];
+    toolNames: string[];
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface AtribdRuntimeOptions {
+    toolTimeoutMs?: number;
+    toolsListTtlMs?: number;
+}
+/** In-process stdio runtime: mounts the primitives and serves them directly. */
+export declare function createAtribdRuntime(options?: AtribdRuntimeOptions): Promise<AtribdRuntime>;
+/**
+ * stdio-to-HTTP proxy shim: a lightweight stdio child that forwards MCP
+ * calls to a host-owned atribd HTTP endpoint. Works against both the
+ * legacy session host and the stateless host (the client's initialize is
+ * answered without session issuance and later requests carry no session).
+ */
+export declare function createAtribdHttpProxyRuntime(endpoint: string, options?: AtribdRuntimeOptions): Promise<AtribdRuntime>;

package/dist/stdio.js

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * stdio surfaces of atribd.
+ *
+ * The stdio shim exists for startup-spawn harnesses that can only spawn
+ * per-thread MCP child processes. On this surface the ambient context
+ * ladder is unchanged: explicit argument > `_meta` carriers > `ATRIB_CONTEXT_ID`
+ * env > harness registry env > fallback file > undefined, per D078/D083.
+ * The stateless explicit-required policy applies to the HTTP surface only.
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { callWithToolTimeout, createAtribdBackend, readPackageVersion, DEFAULT_TOOL_TIMEOUT_MS, } from './backend.js';
+import { createAtribdServer, DEFAULT_TOOLS_LIST_TTL_MS } from './http-host.js';
+/** In-process stdio runtime: mounts the primitives and serves them directly. */
+export async function createAtribdRuntime(options = {}) {
+    const toolTimeoutMs = options.toolTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
+    const toolsListTtlMs = options.toolsListTtlMs ?? DEFAULT_TOOLS_LIST_TTL_MS;
+    const backend = await createAtribdBackend({ toolTimeoutMs });
+    const server = createAtribdServer({
+        getBackend: async () => backend,
+        toolsListTtlMs,
+    });
+    return {
+        server,
+        tools: backend.tools,
+        toolNames: backend.toolNames,
+        flush: backend.flush,
+        close: async () => {
+            await backend.flush();
+            await server.close();
+            await backend.close();
+        },
+    };
+}
+/**
+ * stdio-to-HTTP proxy shim: a lightweight stdio child that forwards MCP
+ * calls to a host-owned atribd HTTP endpoint. Works against both the
+ * legacy session host and the stateless host (the client's initialize is
+ * answered without session issuance and later requests carry no session).
+ */
+export async function createAtribdHttpProxyRuntime(endpoint, options = {}) {
+    const toolTimeoutMs = options.toolTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
+    const upstreamTransport = new StreamableHTTPClientTransport(new URL(endpoint));
+    const upstream = new Client({
+        name: 'atribd-stdio-http-proxy',
+        version: readPackageVersion(),
+    });
+    await upstream.connect(upstreamTransport);
+    const listed = await upstream.listTools();
+    const server = new Server({
+        name: 'atribd-stdio-http-proxy',
+        version: readPackageVersion(),
+    }, {
+        capabilities: { tools: {} },
+        instructions: 'Lightweight stdio proxy for atribd. It forwards MCP calls to a host-owned stateless HTTP daemon.',
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: listed.tools }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        return callWithToolTimeout(request.params.name, toolTimeoutMs, () => upstream.callTool(request.params));
+    });
+    return {
+        server,
+        tools: listed.tools,
+        toolNames: listed.tools.map((tool) => tool.name),
+        flush: async () => { },
+        close: async () => {
+            await Promise.allSettled([server.close(), upstream.close(), upstreamTransport.close()]);
+        },
+    };
+}

package/dist/transport-adapter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Transport adapter boundary (P046).
+ *
+ * The MCP 2026-07-28 spec removes the `initialize`/`initialized` handshake
+ * and the `Mcp-Session-Id` header from Streamable HTTP. The Tier-1
+ * TypeScript SDK gate for that transport binds the transport binding, not
+ * the daemon core, so the daemon isolates "turn one self-describing HTTP
+ * request into MCP server handling" behind this interface. When the SDK
+ * ships stateless-transport support, only the adapter internals swap.
+ *
+ * The current implementation runs the session-era SDK in its documented
+ * stateless mode: a fresh `Server` + `StreamableHTTPServerTransport` pair
+ * per request, `sessionIdGenerator: undefined` (no session id issued, no
+ * session validation, `Mcp-Session-Id` request headers ignored), and JSON
+ * responses instead of SSE. A legacy `initialize` POST is answered with a
+ * valid capabilities response and no session id.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export interface AtribdTransportAdapter {
+    /** Adapter implementation name, surfaced in the health report. */
+    readonly name: string;
+    /** Highest MCP protocol version the adapter speaks. */
+    readonly protocolVersion: string;
+    /**
+     * Handle one self-describing HTTP request. The caller has already parsed
+     * and validated the JSON body (size cap, SEP-2243 routing headers); the
+     * adapter owns JSON-RPC dispatch and the response.
+     */
+    handleRequest(req: IncomingMessage, res: ServerResponse, parsedBody: unknown): Promise<void>;
+}
+export interface SessionSdkStatelessAdapterOptions {
+    /**
+     * Factory for a per-request MCP server wired to the shared backend.
+     * Creating a server per request is what makes any request able to land
+     * on any instance: no transport state survives the response.
+     */
+    serverFactory: () => Server;
+}
+export declare function createSessionSdkStatelessAdapter(options: SessionSdkStatelessAdapterOptions): AtribdTransportAdapter;

package/dist/transport-adapter.js

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
+export function createSessionSdkStatelessAdapter(options) {
+    return {
+        name: 'session-sdk-per-request',
+        protocolVersion: LATEST_PROTOCOL_VERSION,
+        handleRequest: async (req, res, parsedBody) => {
+            const server = options.serverFactory();
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableJsonResponse: true,
+            });
+            const cleanup = () => {
+                void Promise.allSettled([transport.close(), server.close()]);
+            };
+            res.once('close', cleanup);
+            try {
+                await server.connect(transport);
+                await transport.handleRequest(req, res, parsedBody);
+            }
+            finally {
+                res.removeListener('close', cleanup);
+                cleanup();
+            }
+        },
+    };
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@atrib/daemon",
+  "version": "0.1.0",
+  "description": "Local daemon for atrib. Serves the seven cognitive primitives from one stateless-native process over Streamable HTTP or stdio.",
+  "author": "Nader Helmy",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/creatornader/atrib/tree/main/services/atribd",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/creatornader/atrib.git",
+    "directory": "services/atribd"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "atribd": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@atrib/mcp": "0.21.0",
+    "@atrib/emit": "0.17.3",
+    "@atrib/annotate": "0.2.41",
+    "@atrib/recall": "0.14.7",
+    "@atrib/summarize": "0.4.23",
+    "@atrib/trace": "0.5.21",
+    "@atrib/revise": "0.2.41",
+    "@atrib/verify-mcp": "0.2.22"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8",
+    "zod": "^4.4.3"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc && chmod +x dist/index.js",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}