@smartmemory/compose 0.3.6-beta → 0.3.7

package/lib/stratum-mcp-client.js

@@ -19,10 +19,49 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import YAML from 'yaml';
 import { validateBuildStreamEvent } from './build-stream-schema.js';
+import { appendEvent, resolveDispatchLedgerCwd } from './dispatch-ledger.js';
 import { resolveStratumMcpConnection } from './stratum-engine.js';
 
 const RUNTIME_INPUT_REF = /^\$\.input\.([A-Za-z_][A-Za-z0-9_]*)$/;
 
+function finiteOrNull(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function nonemptyStringOrNull(value) {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function isBlockedDispatch(value) {
+  const candidates = [
+    value?.status,
+    value?.outcome,
+    value?.code,
+    value?.error?.status,
+    value?.error?.code,
+  ];
+  return candidates.some((candidate) => {
+    const normalized = typeof candidate === 'string' ? candidate.toLowerCase() : '';
+    return normalized === 'blocked'
+      || normalized === 'budget_exhausted'
+      || normalized === 'budget-exhausted';
+  });
+}
+
+function attachDispatchId(value, dispatchId) {
+  if ((typeof value !== 'object' && typeof value !== 'function') || value === null) return;
+  try {
+    Object.defineProperty(value, 'dispatchId', {
+      configurable: true,
+      enumerable: false,
+      value: dispatchId,
+    });
+  } catch {
+    // A frozen third-party value cannot carry metadata. Dispatch behavior still
+    // wins over observability.
+  }
+}
+
 /**
  * Resolve producer-owned authoring values that TS v1 deliberately requires to
  * be literals. Compose knows these values at plan time, so mutate a cloned spec
@@ -147,6 +186,86 @@ export class StratumMcpClient {
   // STRAT-PAR-STREAM: subscribers keyed by `${flowId}::${stepId}` → Set<handler>
   #eventSubs = new Map();
 
+  #recordAgentDispatch(dispatchId, agentType, opts, resultOrError, outcome, elapsedMs) {
+    try {
+      const context = opts.telemetry && typeof opts.telemetry === 'object'
+        ? opts.telemetry
+        : {};
+      const returnedTelemetry = resultOrError?.telemetry
+        && typeof resultOrError.telemetry === 'object'
+        ? resultOrError.telemetry
+        : {};
+      const usage = resultOrError?.usage && typeof resultOrError.usage === 'object'
+        ? resultOrError.usage
+        : {};
+      const effortIntended = Object.hasOwn(context, 'effort_intended')
+        ? nonemptyStringOrNull(context.effort_intended)
+        : nonemptyStringOrNull(opts.effort);
+      const event = {
+        kind: 'dispatch',
+        dispatch_id: dispatchId,
+        site: nonemptyStringOrNull(context.site) ?? 'unattributed',
+        agent: String(agentType ?? 'claude').split(':', 1)[0] || 'claude',
+        outcome,
+        model: nonemptyStringOrNull(returnedTelemetry.model)
+          ?? nonemptyStringOrNull(usage.model),
+        effort_intended: effortIntended,
+        effort_executed: nonemptyStringOrNull(returnedTelemetry.effort),
+        tokens_in: null,
+        tokens_out: null,
+        tokens_total: finiteOrNull(usage.tokens),
+        usd: finiteOrNull(usage.usd),
+        duration_ms: finiteOrNull(usage.ms)
+          ?? finiteOrNull(returnedTelemetry.durationMs)
+          ?? finiteOrNull(elapsedMs),
+      };
+      for (const [field, value] of [
+        ['build_id', context.build_id],
+        ['feature_code', context.feature_code],
+        ['step_id', context.step_id],
+      ]) {
+        if (nonemptyStringOrNull(value) !== null) event[field] = value;
+      }
+      if (finiteOrNull(context.attempt) !== null) event.attempt = context.attempt;
+      appendEvent(resolveDispatchLedgerCwd(context.project_cwd), event);
+    } catch {
+      // Dispatch capture is fail-open by contract.
+    }
+  }
+
+  async #dispatchAgentRun(agentType, prompt, opts, callOpts) {
+    const dispatchId = randomUUID();
+    const startedAt = Date.now();
+    try {
+      const result = await this.#callTool(
+        'stratum_agent_run',
+        buildAgentRunRequest(agentType, prompt, opts),
+        callOpts,
+      );
+      this.#recordAgentDispatch(
+        dispatchId,
+        agentType,
+        opts,
+        result,
+        isBlockedDispatch(result) ? 'blocked' : 'ok',
+        Date.now() - startedAt,
+      );
+      attachDispatchId(result, dispatchId);
+      return result;
+    } catch (error) {
+      this.#recordAgentDispatch(
+        dispatchId,
+        agentType,
+        opts,
+        error,
+        isBlockedDispatch(error) ? 'blocked' : 'error',
+        Date.now() - startedAt,
+      );
+      attachDispatchId(error, dispatchId);
+      throw error;
+    }
+  }
+
   /**
    * Subscribe to BuildStreamEvent push notifications scoped to a (flowId, stepId).
    * Handler receives a parsed BuildStreamEvent envelope. Returns an unsubscribe fn.
@@ -515,9 +634,12 @@ export class StratumMcpClient {
     // those knobs are resolved compose-side (resolveAgentConfig) and applied at
     // this seam — the engine's connector honors model + sandboxMode. `cwd` is
     // required, so default to the process cwd when the caller omits it.
-    return this.#callTool('stratum_agent_run',
-      buildAgentRunRequest(agentType, prompt, opts),
-      { subscribeProgress: true, correlationId });
+    return this.#dispatchAgentRun(
+      agentType,
+      prompt,
+      opts,
+      { subscribeProgress: true, correlationId },
+    );
   }
 
   /**
@@ -531,9 +653,12 @@ export class StratumMcpClient {
    * @returns {Promise<string>}
    */
   async runAgentText(agentType, prompt, opts = {}) {
-    const result = await this.#callTool('stratum_agent_run',
-      buildAgentRunRequest(agentType, prompt, opts),
-      { subscribeProgress: false });
+    const result = await this.#dispatchAgentRun(
+      agentType,
+      prompt,
+      opts,
+      { subscribeProgress: false },
+    );
     return result?.text ?? '';
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.3.6-beta",
+  "version": "0.3.7",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",
@@ -85,7 +85,7 @@
     "@radix-ui/react-toggle": "^1.1.10",
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.8",
-    "@smartmemory/stratum": "0.3.2",
+    "@smartmemory/stratum": "^0.3.3",
     "@tanstack/react-virtual": "^3.13.23",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",

package/server/compose-mcp-tools.js

@@ -835,6 +835,21 @@ export async function toolJudgmentLedgerAppend(args) {
   return judgmentLedgerAppend(getTargetRoot(), args);
 }
 
+export async function toolJudgmentPersonWrite(args) {
+  const { judgmentPersonWrite } = await import('../lib/judgment-writer.js');
+  return judgmentPersonWrite(getTargetRoot(), args);
+}
+
+export async function toolJudgmentSituationWrite(args) {
+  const { judgmentSituationWrite } = await import('../lib/judgment-writer.js');
+  return judgmentSituationWrite(getTargetRoot(), args);
+}
+
+export async function toolJudgmentGoalWrite(args) {
+  const { judgmentGoalWrite } = await import('../lib/judgment-writer.js');
+  return judgmentGoalWrite(getTargetRoot(), args);
+}
+
 export async function toolGetJudgmentState() {
   const { getJudgmentState } = await import('../lib/judgment-writer.js');
   return getJudgmentState(getTargetRoot());
@@ -931,4 +946,3 @@ export function assertToolPhaseAllowed(tool, args = {}, _testCtx) {
     throw e;
   }
 }
-

package/server/compose-mcp.js

@@ -73,6 +73,9 @@ import {
   toolJudgmentJointAdd,
   toolJudgmentTransition,
   toolJudgmentLedgerAppend,
+  toolJudgmentPersonWrite,
+  toolJudgmentSituationWrite,
+  toolJudgmentGoalWrite,
   toolGetJudgmentState,
   _getBinding,
   assertToolPhaseAllowed,
@@ -790,14 +793,103 @@ const TOOLS = [
         prediction_ref: { type: 'string' },
         prediction_grade: { type: 'string', description: 'right|right-wrong-reason|wrong' },
         reason: { type: 'string' },
+        rests_on: { type: 'array', description: 'On commit-moment decide: goal clause refs (goal:v<N>#c<N>) the commit rests on; resolved through the effective goal chain.' },
         anchor: { type: 'string', description: 'On note: projection anchor (register-header, joint:<slug>, …).' },
         idempotency_key: { type: 'string' },
       },
     },
   },
+  {
+    name: 'judgment_person_write',
+    description: 'Write person canon by op. create adds a person; open_field supports create, fill, and reopen; edge/load_link support create and remove; correct supports divergence pair/clear. Provenance is writer-stamped.',
+    inputSchema: {
+      type: 'object',
+      required: ['op'],
+      properties: {
+        op: { type: 'string', enum: ['create', 'add_fact', 'correct', 'open_field', 'edge', 'load_link'] },
+        slug: { type: 'string' },
+        display_name: { type: 'string' },
+        section: { type: 'string', description: 'role|life|stated|revealed' },
+        text: { type: 'string' },
+        channel: { type: 'string', description: 'said|observed|secondhand|inferred' },
+        via: { type: 'string', description: 'Source attribution for a secondhand fact; not provenance.' },
+        at: { type: 'string', description: 'ISO date (YYYY-MM-DD).' },
+        fact_id: { type: 'string' },
+        pair_with: { type: 'string', description: 'Pair stated↔revealed divergence on correct.' },
+        clear: { type: 'array', description: 'On correct: exactly ["diverges_with"].', items: { type: 'string' } },
+        name: { type: 'string', description: 'open_field create branch.' },
+        open_field_id: { type: 'string' },
+        filled_by: { type: 'string' },
+        reopen: { type: 'boolean' },
+        reason: { type: 'string' },
+        to: { type: 'string', description: 'edge create branch target person slug.' },
+        kind: { type: 'string', description: 'edge create branch kind.' },
+        edge_id: { type: 'string' },
+        remove: { type: 'boolean' },
+        fact: { type: 'string', description: 'load_link create branch fact ID.' },
+        carries: { type: 'string' },
+        load_link_id: { type: 'string' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'judgment_situation_write',
+    description: 'Write situation-entity canon by op. create adds an entity; owed supports create, give, and reopen; load_link supports create and remove. Provenance is writer-stamped.',
+    inputSchema: {
+      type: 'object',
+      required: ['op'],
+      properties: {
+        op: { type: 'string', enum: ['create', 'add_fact', 'correct', 'owed', 'load_link'] },
+        slug: { type: 'string' },
+        display_name: { type: 'string' },
+        text: { type: 'string' },
+        channel: { type: 'string', description: 'said|observed|secondhand|inferred' },
+        via: { type: 'string', description: 'Source attribution for a secondhand fact; not provenance.' },
+        at: { type: 'string', description: 'ISO date (YYYY-MM-DD).' },
+        fact_id: { type: 'string' },
+        name: { type: 'string', description: 'owed create branch.' },
+        why_load_bearing: { type: 'string' },
+        owed_id: { type: 'string' },
+        filled_by: { type: 'string' },
+        reopen: { type: 'boolean' },
+        reason: { type: 'string' },
+        remove: { type: 'boolean' },
+        fact: { type: 'string', description: 'load_link create branch fact ID.' },
+        carries: { type: 'string' },
+        load_link_id: { type: 'string' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'judgment_goal_write',
+    description: 'Write goal canon by op. Ordinary cuts require elicited clauses, provocation, and owner ratification. Every non-migrate op is migration-locked while a live legacy objective requires migration; migrate is the one-shot, fail-closed cutover that lifts the lock and takes no payload. joint_link/load_link support create and remove. Provenance and intents are writer-owned.',
+    inputSchema: {
+      type: 'object',
+      required: ['op'],
+      properties: {
+        op: { type: 'string', enum: ['cut', 'correct', 'joint_link', 'load_link', 'migrate'] },
+        clauses: { type: 'array', description: 'cut: {text, channel, elicitation, secondhand source attribution?}[]' },
+        provocation: { type: 'object', description: 'cut: {quote, at}' },
+        ratification: { type: 'object', description: 'cut: {asked, answered_at, answer_ref, quote}' },
+        diff_note: { type: 'string' },
+        clause_id: { type: 'string', description: 'correct branch clause ID.' },
+        text: { type: 'string', description: 'correct branch replacement wording.' },
+        joint: { type: 'string', description: 'joint_link create branch joint slug.' },
+        joint_link_id: { type: 'string' },
+        remove: { type: 'boolean' },
+        reason: { type: 'string' },
+        clause: { type: 'string', description: 'load_link create branch v<N>#c<N> reference.' },
+        carries: { type: 'string' },
+        load_link_id: { type: 'string' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
   {
     name: 'get_judgment_state',
-    description: 'Judgment canon snapshot: positions (derived status), joints, under-test, open predictions, recent ledger. Replays pending transition intents first.',
+    description: 'Judgment canon snapshot: positions (derived status), joints, under-test, open predictions, recent ledger. Replays pending judgment intents first.',
     inputSchema: { type: 'object', properties: {} },
   },
 ];
@@ -898,6 +990,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'judgment_joint_add':       result = await toolJudgmentJointAdd(args); break;
       case 'judgment_transition':      result = await toolJudgmentTransition(args); break;
       case 'judgment_ledger_append':   result = await toolJudgmentLedgerAppend(args); break;
+      case 'judgment_person_write':    result = await toolJudgmentPersonWrite(args); break;
+      case 'judgment_situation_write': result = await toolJudgmentSituationWrite(args); break;
+      case 'judgment_goal_write':      result = await toolJudgmentGoalWrite(args); break;
       case 'get_judgment_state':       result = await toolGetJudgmentState(args); break;
       // agent_run removed — STRAT-DEDUP-AGENTRUN v1. Use mcp__stratum__stratum_agent_run.
       default:

package/server/mcp-tool-policy.js

@@ -36,7 +36,7 @@ const REVIEWER_ALLOW = [
   'get_pending_gates', 'get_changelog_entries', 'get_journal_entries', 'get_completions',
   'validate_feature', 'validate_project', 'roadmap_diff', 'get_roadmap', 'roadmap_graph_check', 'assess_feature_artifacts',
   'set_workspace', 'get_workspace', 'bind_session',
-  'get_judgment_state', // COMP-JUDGMENT-WRITER: read-only; the five judgment write tools stay reviewer-denied
+  'get_judgment_state', // COMP-JUDGMENT-WRITER: read-only; the eight judgment write tools stay reviewer-denied
 ];
 
 export const PROFILE_POLICY = {