create-principles-disciple 1.147.6 → 1.147.8

package/pd-mcp-server/dist/logging.d.ts

@@ -4,7 +4,8 @@ export type LogLevel = 'info' | 'warn' | 'error';
 /** Bound logger: sink fixed at construction, ≤3 params per call. */
 export type LogFn = (level: LogLevel, event: string, fields?: LogFields) => void;
 declare function sanitizeErrorKind(err: unknown): string;
-/** Default stderr sink. One JSON line per event, nothing else. */
+/** Default stderr sink. One JSON line per event, nothing else.
+ * A closed/broken stderr pipe must never turn into a process-level failure. */
 export declare function stderrSink(line: string): void;
 export declare function createLogger(sink: (line: string) => void, baseFields?: LogFields): LogFn;
 /** Convenience logger bound to stderr (startup/shutdown paths). */

package/pd-mcp-server/dist/logging.js

@@ -16,25 +16,36 @@ function sanitizeErrorKind(err) {
     }
     return 'Error';
 }
-/** Default stderr sink. One JSON line per event, nothing else. */
+/** Default stderr sink. One JSON line per event, nothing else.
+ * A closed/broken stderr pipe must never turn into a process-level failure. */
 export function stderrSink(line) {
-    process.stderr.write(line + '\n');
+    try {
+        process.stderr.write(line + '\n');
+    }
+    catch {
+        // Logging must never affect the service.
+    }
 }
 export function createLogger(sink, baseFields) {
     return (level, event, fields) => {
-        const entry = {
-            ts: new Date().toISOString(),
-            server: SERVER_NAME,
-            version: SERVER_VERSION,
-            level,
-            event,
-        };
-        const merged = { ...baseFields, ...fields };
-        for (const [k, v] of Object.entries(merged)) {
-            if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
-                entry[k] = v;
+        try {
+            const entry = {
+                ts: new Date().toISOString(),
+                server: SERVER_NAME,
+                version: SERVER_VERSION,
+                level,
+                event,
+            };
+            const merged = { ...baseFields, ...fields };
+            for (const [k, v] of Object.entries(merged)) {
+                if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
+                    entry[k] = v;
+            }
+            sink(JSON.stringify(entry));
+        }
+        catch {
+            // Logging must never affect the caller (MCP tool calls included).
         }
-        sink(JSON.stringify(entry));
     };
 }
 /** Convenience logger bound to stderr (startup/shutdown paths). */

package/pd-mcp-server/dist/server.js

@@ -16,7 +16,7 @@ import { z } from 'zod';
 import { recallPrinciplePainsCapability, } from '@principles/core/runtime-v2/pain-recall-capability';
 import { runWithDeadline, OrphanLimiter, AdmissionLimiter, DEFAULT_DEADLINE_MS } from './deadline.js';
 import { assembleResult, adapterFailureEnvelope, textResult } from './envelope.js';
-import { RESPONSE_BUDGET_BYTES, withinBudget } from './budget.js';
+import { withinBudget } from './budget.js';
 import { createLogger, sanitizeErrorKind, stderrSink } from './logging.js';
 import { SERVER_NAME, SERVER_VERSION } from './version.js';
 export const TOOL_NAME = 'pd_recall_principle_pains';
@@ -56,6 +56,16 @@ function executionFailedResult(message) {
 function shuttingDownResult() {
     return executionFailedResult('The server is shutting down; the call was not completed.');
 }
+/** Byte size of the text this call actually returned (never the input). */
+function resultTextBytes(result) {
+    try {
+        const [first] = result.content;
+        return first === undefined ? 0 : Buffer.byteLength(first.text, 'utf8');
+    }
+    catch {
+        return 0;
+    }
+}
 /**
  * Build the PD MCP server (not yet connected to any transport).
  *
@@ -87,16 +97,28 @@ export function createPdMcpServer(options) {
         // this, N concurrent requests all pass an orphan-count check while none
         // has timed out yet and N > limit capability calls start.
         if (shuttingDown) {
-            log('warn', 'tool_call_refused_shutting_down', { durationMs: Date.now() - startedAt });
-            return shuttingDownResult();
+            const refused = shuttingDownResult();
+            log('warn', 'tool_call', {
+                toolName: TOOL_NAME,
+                durationMs: Date.now() - startedAt,
+                status: 'unavailable',
+                errorCode: 'shutting_down',
+                responseBytes: resultTextBytes(refused),
+                truncated: false,
+            });
+            return refused;
         }
         if (!admissions.tryAcquire()) {
-            log('warn', 'tool_call_refused_saturated', {
+            const saturated = executionFailedResult('The server is already executing the maximum number of concurrent calls; retry shortly.');
+            log('warn', 'tool_call', {
+                toolName: TOOL_NAME,
                 durationMs: Date.now() - startedAt,
-                active: admissions.active,
-                max: admissions.max,
+                status: 'unavailable',
+                errorCode: 'saturated',
+                responseBytes: resultTextBytes(saturated),
+                truncated: false,
             });
-            return executionFailedResult('The server is already executing the maximum number of concurrent calls; retry shortly.');
+            return saturated;
         }
         // The window covers validation → capability → projection →
         // serialization; validation of the parsed input is part of the race.
@@ -114,8 +136,14 @@ export function createPdMcpServer(options) {
                     limit: parsed.limit,
                 });
                 const assembled = assembleResult(envelope);
-                if (assembled.ok)
-                    return { kind: 'envelope', result: assembled.result };
+                if (assembled.ok) {
+                    return {
+                        kind: 'envelope',
+                        result: assembled.result,
+                        status: envelope.status,
+                        errorCode: envelope.error?.code ?? 'none',
+                    };
+                }
                 return { kind: 'overBudget', bytes: assembled.overBudgetBytes };
             }
             catch (err) {
@@ -132,36 +160,63 @@ export function createPdMcpServer(options) {
         if (outcome.ok) {
             switch (outcome.value.kind) {
                 case 'envelope': {
-                    log('info', 'tool_call_completed', { durationMs, resultKind: 'envelope' });
+                    log('info', 'tool_call', {
+                        toolName: TOOL_NAME,
+                        durationMs,
+                        status: outcome.value.status,
+                        errorCode: outcome.value.errorCode,
+                        responseBytes: resultTextBytes(outcome.value.result),
+                        truncated: false,
+                    });
                     return outcome.value.result;
                 }
                 case 'overBudget': {
-                    log('warn', 'tool_call_over_budget', { durationMs, bytes: outcome.value.bytes, budget: RESPONSE_BUDGET_BYTES });
                     const failure = adapterFailureEnvelope('response_budget_exceeded', 'The response exceeded the 32 KiB MCP budget and was withheld without truncation.');
                     const failureJson = JSON.stringify(failure);
-                    if (!withinBudget(failureJson)) {
-                        // Cannot happen (static shell), but fail loud over silent breakage.
-                        log('error', 'failure_envelope_over_budget', {});
-                    }
-                    return textResult(failureJson, true);
+                    // A static shell that cannot fit is a hard defect; surface it in the
+                    // same tool_call record instead of emitting a second event.
+                    const failureCode = withinBudget(failureJson)
+                        ? 'response_budget_exceeded'
+                        : 'failure_envelope_over_budget';
+                    const withheld = textResult(failureJson, true);
+                    log('warn', 'tool_call', {
+                        toolName: TOOL_NAME,
+                        durationMs,
+                        status: 'unavailable',
+                        errorCode: failureCode,
+                        responseBytes: resultTextBytes(withheld),
+                        truncated: false,
+                    });
+                    return withheld;
                 }
                 case 'exception': {
                     // Sanitized category only — no message, no stack, no paths.
-                    log('error', 'tool_call_unexpected_exception', { durationMs, errorKind: outcome.value.errorKind });
-                    return executionFailedResult('The call failed unexpectedly; the error was logged server-side with a sanitized category only.');
+                    const failed = executionFailedResult('The call failed unexpectedly; the error was logged server-side with a sanitized category only.');
+                    log('error', 'tool_call', {
+                        toolName: TOOL_NAME,
+                        durationMs,
+                        status: 'unavailable',
+                        errorCode: 'tool_execution_failed',
+                        responseBytes: resultTextBytes(failed),
+                        truncated: false,
+                    });
+                    return failed;
                 }
             }
         }
         // Deadline exceeded (§4.7): stop waiting, suppress the late result,
         // report an Adapter execution failure. Not underlying cancellation:
         // the capacity slot stays reserved until the orphan settles.
-        log('warn', 'tool_call_deadline_exceeded', {
+        const timedOut = executionFailedResult(`The call exceeded the ${deadlineMs} ms deadline; the late result is suppressed and will not be delivered.`);
+        log('warn', 'tool_call', {
+            toolName: TOOL_NAME,
             durationMs,
-            deadlineMs,
-            active: admissions.active,
-            orphans: orphans.size,
+            status: 'unavailable',
+            errorCode: 'deadline_exceeded',
+            responseBytes: resultTextBytes(timedOut),
+            truncated: false,
         });
-        return executionFailedResult(`The call exceeded the ${deadlineMs} ms deadline; the late result is suppressed and will not be delivered.`);
+        return timedOut;
     });
     return {
         mcpServer,
@@ -169,7 +224,6 @@ export function createPdMcpServer(options) {
         admissions,
         beginShutdown() {
             shuttingDown = true;
-            log('info', 'shutdown_begun', { orphans: orphans.size, active: admissions.active });
         },
         isShuttingDown() {
             return shuttingDown;

package/pd-mcp-server/dist/version.d.ts

@@ -7,7 +7,7 @@
  * package.json. A unit test pins it to package.json so the two cannot drift.
  */
 export declare const SERVER_NAME: 'pd-mcp-server';
-export declare const SERVER_VERSION: '0.2.2';
+export declare const SERVER_VERSION: '0.3.0';
 /** The only MCP SDK family/version this server is released against
  * (Gate 4-A freeze, PD_MCP_GATE4A_REALITY_CHECK §3). Exact pin — no ranges. */
 export declare const MCP_SDK_PIN: '@modelcontextprotocol/server@2.4.0';

package/pd-mcp-server/dist/version.js

@@ -7,7 +7,7 @@
  * package.json. A unit test pins it to package.json so the two cannot drift.
  */
 export const SERVER_NAME = 'pd-mcp-server';
-export const SERVER_VERSION = '0.2.2';
+export const SERVER_VERSION = '0.3.0';
 /** The only MCP SDK family/version this server is released against
  * (Gate 4-A freeze, PD_MCP_GATE4A_REALITY_CHECK §3). Exact pin — no ranges. */
 export const MCP_SDK_PIN = '@modelcontextprotocol/server@2.4.0';

package/pd-mcp-server/dist/workspace.d.ts

@@ -5,12 +5,15 @@ export interface WorkspaceBinding {
     readonly workspaceDir: string;
     readonly host: string | null;
 }
+export type WorkspaceBindingFailureCode = 'workspace_env_missing' | 'workspace_not_absolute' | 'workspace_unreadable' | 'workspace_not_directory' | 'host_invalid';
 export type WorkspaceBindingResolution = {
     readonly ok: true;
     readonly binding: WorkspaceBinding;
 } | {
     readonly ok: false;
     readonly reason: string;
+    /** Stable machine-readable code (safe for logs; never a path). */
+    readonly reasonCode: WorkspaceBindingFailureCode;
     readonly envVar: string;
     readonly nextAction: string;
 };

package/pd-mcp-server/dist/workspace.js

@@ -30,6 +30,7 @@ export function resolveWorkspaceBinding(env) {
         return {
             ok: false,
             reason: 'workspace binding env is missing or empty',
+            reasonCode: 'workspace_env_missing',
             envVar: WORKSPACE_DIR_ENV,
             nextAction: `Re-run the PD host setup (this writes the PD-owned mcp-binding.json and launches via launcher.cjs). Do not set ${WORKSPACE_DIR_ENV} by hand from agent context.`,
         };
@@ -38,6 +39,7 @@ export function resolveWorkspaceBinding(env) {
         return {
             ok: false,
             reason: 'workspace binding is not an absolute path',
+            reasonCode: 'workspace_not_absolute',
             envVar: WORKSPACE_DIR_ENV,
             nextAction: 'Re-run the PD host setup so the binding records the absolute governance workspace directory.',
         };
@@ -50,6 +52,7 @@ export function resolveWorkspaceBinding(env) {
         return {
             ok: false,
             reason: 'workspace binding directory does not exist or is not readable',
+            reasonCode: 'workspace_unreadable',
             envVar: WORKSPACE_DIR_ENV,
             nextAction: 'Re-run the PD host setup; if the workspace was moved, re-install PD for this host so the binding is regenerated.',
         };
@@ -58,6 +61,7 @@ export function resolveWorkspaceBinding(env) {
         return {
             ok: false,
             reason: 'workspace binding is not a directory',
+            reasonCode: 'workspace_not_directory',
             envVar: WORKSPACE_DIR_ENV,
             nextAction: 'Re-run the PD host setup so the binding points at the governance workspace directory.',
         };
@@ -68,6 +72,7 @@ export function resolveWorkspaceBinding(env) {
             return {
                 ok: false,
                 reason: 'host marker is not one of the known PD hosts',
+                reasonCode: 'host_invalid',
                 envVar: HOST_ENV,
                 nextAction: 'Re-run the PD host setup; the host marker is written by the PD installer and must not be edited.',
             };

package/pd-mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/pd-mcp-server",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Principles Disciple MCP Server — the single shared MCP server implementation for the three PD hosts (Codex, OpenClaw, WorkBuddy). Read-only pain recall through the Gate 3 Capability (SPEC-PD-MCP-GATE4-001).",
   "type": "module",
   "main": "./dist/index.js",