@agdf/mcp-server 0.30.0 → 0.31.0

package/README.md

@@ -85,8 +85,18 @@ Unknown/unowned partial states remain blocked. Successful setup returns creation
 `agdf_run/run.create` creates an unapproved Run from a semantic title and original operation UUID;
 pre-Run `operation-status` resolves a lost response without inventing a second Run.
 `authoring-inputs` returns versioned templates and exact sources with bounded cursors.
-`agdf_record/material.stage` transfers at most 16 KiB per part and 128 KiB per file, then seals
-Core-owned references for existing typed writers, including reviewed formal artefacts, unapproved
+`authoring-inputs.material_call` supplies a bound form: fill its UTF-8 content and use
+`agdf_record/material.stage` action `put` to seal files of at most 48 KiB each within the 64 KiB whole JSON request bound in one call.
+The Core computes byte counts, material identities and digests. Larger files retain the bounded
+multipart path (16 KiB per part, 128 KiB per file). Each multipart action has its own operation UUID;
+only an identical retry reuses a UUID. Returned `recording_calls` provide the binding and material
+reference; fill only the listed author/review fields. Ready `next_calls` are executable as supplied;
+do not add intake/revision fields to a supplied `continue_delivery` dispatch.
+Pass authored Markdown as UTF-8 string data through structured input. If a host uses JavaScript,
+author with its file-editing tool and pass the UTF-8 file read as the content value; embedding
+the whole document in a backtick literal makes Markdown syntax executable JavaScript syntax.
+This guidance adds no server-side file reader and changes no byte or input limit.
+These Core-owned references feed existing typed writers, including reviewed formal artefacts, unapproved
 UR replacement, Verified Change and closeout. Code edits, actual tests and Git execution remain
 external work; none of these operations grants approval.
 
@@ -246,3 +256,17 @@ They do not qualify an installed host or another OS. The fixed performance test
 the actual owned plugin launcher with 20/20 samples and p95 limits of 2500 ms cold /
 1000 ms warm. Performance acceptance and native qualification are separate
 required evidence, not consequences of the topology declaration.
+
+The normal MCP path is `next_action.call`: either a ready call forwarded unchanged or a form with named `required_inputs` such as `content`, `title`, `reviewer`, `reviewed` or `response`. The adapter maps those names to the stored canonical payload fields. It retains the original target, Run, revision, permission group and operation UUID; it never fills authored content, review attestations or approval replies. The former competing `submit` form is absent. Raw requests remain accepted for compatibility, but the full original request is exposed only under the explicit `recovery_only` branch, with the exact field map and original UUID. Retain that branch and the actual submitted inputs for uncertain-outcome recovery; do not generate a replacement identity.
+
+Verified owned plugin launchers retain offered templates in a private bounded journal under their existing MCP data root. The namespace includes the serving surface, version and server/dispatcher/SDK identity. A reconnect at that same identity can resolve the original reference without a new UUID or refreshed revision. The original 30-minute lifetime is never renewed. No submitted author/review/reply inputs or execution receipts are added to this journal; it is transport storage, not canonical Run State or authority. Direct transports without this verified owner remain connection-local. Private material buffers have their separate existing generation lifetime and still require exact semantic-byte recovery after generation loss.
+
+Empty, malformed, unknown and known-expired references remain distinct. An unavailable live reference returns `prepared_call_unknown`, rather than blaming the authored command schema. Store failures are distinguished from missing references. A failed publication of a future reference never discards an already successful operation receipt; its exact original request remains in recovery. Every restored call still passes the current SDK, permission-group, Core and revision checks.
+
+For a unique Core-supplied normal next step, the adapter may execute one exact `agdf_inspect` call for `authoring-inputs`, `gate-check` or `operation-contract` and include it as `next_read.result`. `next_action.context_path` names that already-loaded context. The original operation outcome and receipt remain intact if this separate read fails. No dispatch, write, presentation or approval is chained automatically; `agdf_dispatch` is not read-only. Source pagination remains explicit. Internal read attempts/failures are accounted separately from outer MCP invocations in native observations.
+
+`authoring-inputs` supports `bundle:true` for bounded multi-document pages. Read every chunk and cursor without a duplicate writer-contract lookup. A retained first-page form is reusable only for the same exact manifest and an available connection reference; otherwise use the supplied first-page read. Page transport does not prove source review.
+
+Prepared references also retain explicitly offered `agdf_inspect` reads, including source pages, contract help and original-operation status. Read inputs stay `{}`; the original SDK schema validates the complete supplied request before registration. Target, Run, revision, cursor and original status selection are never inferred or refreshed. The actual `next_read.tool/arguments` remain the record of an already executed read; its separate `next_read.call` is the exact prepared retry. Explicit recovery reads remain Raw for reconnect, and dispatch retains its original schema. No reference changes permission or bypasses canonical validation.
+
+Bundled authoring reports use `document_bundle_v2`: `documents` contains complete text, `document_manifest` is metadata only, and `fragments` must be joined by identity and byte offsets across all cursors before editing. Missing content must never be coerced into a replacement string.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agdf/mcp-server",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Local MCP adapter for version-matched AGDF dispatch and control inspection.",
   "type": "module",
   "files": [
@@ -23,7 +23,7 @@
   "scripts": {},
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
-    "create-agdf": "0.30.0"
+    "create-agdf": "0.31.0"
   },
   "engines": {
     "node": ">=22"

package/src/generation-runtime.js

@@ -12,6 +12,11 @@ export function startGenerationRuntime({ epoch, generation, channel }) {
     return { ...owned, inflight: inflight + (starting ? 1 : 0) + (owned.inflight ?? 0),
       executor: executor?.active ? 1 : 0, uncertain: unknown.size + (owned.uncertain ?? 0), closing };
   }
+  // Companion events (SD SDD-006): this generation executed the call, so it journals the final result
+  // once, before the result leaves; a failing journal never changes or delays the result.
+  function journal(name, args, projected) {
+    try { runtime.observeOutcome?.(name, args, projected); } catch { /* notification only */ }
+  }
   function send(input, kind, payload) {
     const reply = generationMessage(epoch, generation, kind, payload, {}, input.original_operation_id, input.request_id);
     if (validGenerationMessage(reply, { epoch, generation, reply: true })) channel.send(reply);
@@ -76,11 +81,15 @@ export function startGenerationRuntime({ epoch, generation, channel }) {
           if (input.original_operation_id && result.outcome === 'effect_unknown') unknown.add(input.original_operation_id);
           if (name === 'agdf_inspect' && args.operation === 'operation-status' && result.report?.status === 'recorded'
             && (result.report.receipt?.operation_id ?? result.report.receipt?.operation?.operation_id) === args.module.split('/').at(-1)) unknown.delete(args.module.split('/').at(-1));
-          send(input, 'result', runtime.projectToolResult(name, args, result));
+          const projected = runtime.projectToolResult(name, args, result);
+          journal(name, args, projected);
+          send(input, 'result', projected);
         } catch (error) {
           const facts = runtime.normalizeFailure(error, { phase });
           if (input.original_operation_id && facts.dispatch !== 'not_dispatched') unknown.add(input.original_operation_id);
-          send(input, 'result', runtime.projectToolResult(name, args, runtime.failure(facts.code, name, args, { ...facts, elapsed_ms: performance.now() - started }), facts));
+          const projected = runtime.projectToolResult(name, args, runtime.failure(facts.code, name, args, { ...facts, elapsed_ms: performance.now() - started }), facts);
+          journal(name, args, projected);
+          send(input, 'result', projected);
         } finally { --inflight; }
       }
     } catch (error) { if (input.kind === 'qualify') starting = false; send(input, 'failure', { reason: generationFailureReason(error) }); }

package/src/main.js

@@ -73,6 +73,7 @@ export async function runMcpServer({ surface, cockpitDir, cockpitMode, runtime,
   const handle = serveAgdfStdio({
     runtime,
     executor: dispatchExecutor,
+    preparedCallStore: ownedPublication ? ownedPublisher?.preparedCallStore?.({ surface }) : undefined,
     onerror(code) {
       process.stderr.write(`${code}\n`);
     },

package/src/next-action.js

@@ -0,0 +1,227 @@
+const writeTools = new Set(['agdf_project', 'agdf_run', 'agdf_prepare', 'agdf_record', 'agdf_approve', 'agdf_revise', 'agdf_closeout']);
+const knownTools = new Set([...writeTools, 'agdf_inspect', 'agdf_dispatch']);
+const clone = value => structuredClone(value);
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+const canonical = value => JSON.stringify(stable(value));
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  return object(value) ? Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])])) : value;
+}
+function callValue(value) {
+  return object(value) && knownTools.has(value.tool) && object(value.arguments)
+    ? { tool: value.tool, arguments: clone(value.arguments) } : null;
+}
+function formValue(value) {
+  if (!object(value)) return null;
+  const call = callValue(value.call ?? value);
+  if (!call) return null;
+  // A normal mutating action must already be the transport's bound form. Never
+  // promote its Raw recovery branch or reconstruct one from operation metadata.
+  if (writeTools.has(call.tool) && (!Object.hasOwn(call.arguments, 'prepared_call_id')
+    || typeof call.arguments.prepared_call_id !== 'string' || !call.arguments.prepared_call_id
+    || !object(call.arguments.inputs) || Object.keys(call.arguments).some(key => !['prepared_call_id', 'inputs'].includes(key)))) return null;
+  if (value.required_inputs !== undefined && (!Array.isArray(value.required_inputs)
+    || value.required_inputs.some(field => typeof field !== 'string' || !field))) return null;
+  const source = clone(value);
+  delete source.tool; delete source.arguments;
+  return { ...source, call, required_inputs: Array.isArray(value.required_inputs) ? clone(value.required_inputs) : [] };
+}
+function uniqueForms(values) {
+  const forms = new Map();
+  for (const value of values.filter(Boolean)) {
+    const form = formValue(value);
+    if (!form) return null;
+    const key = canonical({ call: form.call, required_inputs: form.required_inputs });
+    if (!forms.has(key)) forms.set(key, form);
+  }
+  return [...forms.values()];
+}
+function base(state, instruction, source, extra = {}) {
+  return { state, call: null, required_inputs: [], instruction, source, ...extra, authorizes: false };
+}
+function terminal(result, source) {
+  return base('terminal', 'Respect this result\'s terminal host_action and stop; no next tool call is selected.', source,
+    result.host_action ? { host_action: clone(result.host_action) } : {});
+}
+function selectForms(values, source, { forceReply = false, readOnly = false } = {}) {
+  const forms = uniqueForms(values);
+  if (!forms?.length) return base('requires_source', 'No complete normal action was supplied. Read the canonical source or use its explicit recovery instructions; do not construct a replacement call.', source);
+  if (forms.length !== 1) return base('requires_selection', 'Several distinct actions were supplied. Preserve the current binding and obtain the authoritative selection; do not pick the first action.', source);
+  const form = forms[0];
+  if (readOnly && form.call.tool !== 'agdf_inspect') return base('requires_source', 'The supplied continuation is not a read-only page call; no action is selected.', source);
+  const reply = forceReply || form.call.tool === 'agdf_approve' || form.operation?.kind === 'approval.record';
+  if (reply) {
+    // The contract's approval_value is syntax, never a response. A producer that
+    // filled a reply in an offered form cannot establish new human intent here.
+    if (Object.values(form.call.arguments.inputs ?? {}).some(value => value !== '' && value !== undefined))
+      return base('requires_new_reply', 'Obtain a fresh blank approval form and a NEW deliberate reply for its exact presentation. No reply or approval is inferred.', source);
+    return { ...form, state: 'requires_new_reply', source, authorizes: false,
+      instruction: 'Deliver the current presentation before waiting for a NEW deliberate reply. Fill only the supplied reply field from that response; never copy approval_value as a decision. ' + (form.instruction ?? '') };
+  }
+  return { ...form, state: form.required_inputs.length ? 'form' : 'ready', source, authorizes: false,
+    instruction: 'Use this one exact call. Supply only its named required inputs from actual authored content or review; do not rebuild IDs, bindings or a Raw envelope. ' + (form.instruction ?? '') };
+}
+function authoringKey(result, report) {
+  if (report.format !== 'document_bundle_v2' || !/^sha256:[0-9a-f]{64}$/u.test(report.manifest_digest ?? '')) return null;
+  return canonical({ manifest: report.manifest_digest,
+    target_id: result.target?.target_id ?? result.binding?.target_id ?? report.target_id ?? null,
+    target: result.target?.governance_target ?? result.target?.display_path ?? null,
+    run_id: report.run_id ?? null, revision_id: report.revision_id ?? null, planning: report.planning ?? null,
+    owner: report.authoring_owner ?? null, artifact_language: report.artifact_language ?? null,
+    presentation_language: report.presentation_language ?? null });
+}
+function authoringRevision(key) {
+  const { manifest, ...binding } = JSON.parse(key);
+  return canonical(binding);
+}
+function authoringScope(key) {
+  const { manifest, revision_id, ...scope } = JSON.parse(key);
+  return canonical(scope);
+}
+
+// A connection-local projection of supplied actions, not an executor, permission
+// decision or proof that the model has read/reviewed all source pages.
+export function createNextActionProjection({ maxEntries = 32, isAvailable = () => true } = {}) {
+  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1 || maxEntries > 32) throw Error('next_action_cache_limit_invalid');
+  if (typeof isAvailable !== 'function') throw Error('next_action_availability_invalid');
+  const forms = new Map(), superseded = new Set();
+  function available(form) {
+    const normal = formValue(form);
+    if (!normal) return false;
+    try { return isAvailable(clone(normal.call)) === true; } catch { return false; }
+  }
+  function remember(key, form) {
+    if (!key) return;
+    const revision = authoringRevision(key);
+    if (superseded.has(revision)) return;
+    if (!available(form)) { forms.delete(key); return; }
+    // A newly supplied first-page form for this exact authoring scope replaces
+    // cached forms from its earlier revision. Never refresh their bindings, or
+    // let a later old page revive them. Other targets/Runs/owners stay intact.
+    const scope = authoringScope(key);
+    for (const prior of forms.keys()) if (authoringScope(prior) === scope && authoringRevision(prior) !== revision) {
+      forms.delete(prior); superseded.add(authoringRevision(prior));
+    }
+    while (superseded.size > maxEntries) superseded.delete(superseded.values().next().value);
+    forms.delete(key); forms.set(key, clone(form));
+    while (forms.size > maxEntries) forms.delete(forms.keys().next().value);
+  }
+  function rememberAuthoring(result) {
+    if (result?.terminal === true || result?.outcome !== 'inspect_result' || result.operation !== 'authoring-inputs') return;
+    const report = result.report;
+    if (!object(report) || report.available === false || !report.material_call
+      || report.page_index !== undefined && report.page_index !== 0) return;
+    for (const owner of [result, result.continuation, result.navigation, report, result.family_result].filter(object))
+      if (owner.next_calls !== undefined && owner.next_calls !== null && !Array.isArray(owner.next_calls)
+        || owner.recording_calls !== undefined && owner.recording_calls !== null && !Array.isArray(owner.recording_calls)) return;
+    remember(authoringKey(result, report), report.material_call);
+  }
+  function fromContext(result, source) {
+    if (result.terminal === true) return terminal(result, source);
+    if (['rejected', 'recovery_required', 'effect_unknown', 'invalid_input', 'evaluator_error', 'target_unresolved'].includes(result.outcome))
+      return base('requires_source', 'This operation did not establish a successful normal continuation. Preserve its original receipt and recovery instructions; no write form is selected.', source);
+    const report = object(result.report) ? result.report : null;
+    for (const owner of [result, result.continuation, result.navigation, report, result.family_result].filter(object))
+      if (owner.next_calls !== undefined && owner.next_calls !== null && !Array.isArray(owner.next_calls)
+        || owner.recording_calls !== undefined && owner.recording_calls !== null && !Array.isArray(owner.recording_calls))
+        return base('requires_source', 'The supplied action list is malformed. Preserve the existing outcome and obtain the canonical action source.', source);
+    if (Object.hasOwn(result, 'material_call')) {
+      const material = formValue(result.material_call);
+      // This is an explicit correction after accepted private staging, not a
+      // ready write or permission to bypass the source's recording decision.
+      if (result.outcome !== 'accepted' || result.historical_effect === true || result.source_validation?.recordable !== false
+          || report?.available === false || report?.complete === false
+          || !material || material.call.tool !== 'agdf_record' || material.operation?.kind !== 'material.stage'
+          || material.state === 'transport_unavailable' || material.transport_reason
+          || !material.required_inputs.length || new Set(material.required_inputs).size !== material.required_inputs.length
+          || Object.keys(material.call.arguments.inputs).length || !available(material))
+        return base('requires_source', 'No complete authored correction form was supplied. Preserve the source validation and receipt; obtain the canonical correction source without constructing a new call.', source + '.material_call');
+      const competing = [...(result.recording_calls ?? []), ...(result.next_calls ?? []),
+        ...(result.continuation?.next_calls ?? []), ...(report?.next_calls ?? []),
+        ...(result.navigation?.next_calls ?? []), ...(result.family_result?.next_calls ?? []),
+        ...(result.approval_call ? [result.approval_call] : []), ...(report?.prepared_call ? [report.prepared_call] : []),
+        ...(report?.material_call ? [report.material_call] : [])];
+      if (competing.some(value => !value))
+        return base('requires_source', 'The correction action list is malformed. Preserve the source validation and obtain the canonical correction source.', source + '.material_call');
+      return selectForms([result.material_call, ...competing], source + '.material_call');
+    }
+    if (result.approval_call && result.presentation_delivery && !result.historical_effect && !result.presentation_delivery.historical_delivery
+      && ['accepted', 'already_applied'].includes(result.outcome)) return selectForms([result.approval_call], source + '.approval_call', { forceReply: true });
+    if (Array.isArray(result.recording_calls) && result.recording_calls.length)
+      return selectForms(result.recording_calls, source + '.recording_calls');
+    if (result.operation === 'operation-contract' && report?.prepared_call && report.available === false)
+      return base('requires_source', 'The operation-contract report is unavailable. Preserve its original binding and recovery instructions; no write form is selected.', source + '.report');
+    if (result.operation === 'operation-contract' && report?.prepared_call)
+      return selectForms([report.prepared_call], source + '.report.prepared_call');
+    if (result.operation === 'authoring-inputs' && report) {
+      if (report.available === false)
+        return base('requires_source', 'The authoring source is unavailable. Preserve its original binding and recovery instructions; no staging form is selected.', source + '.report');
+      const key = authoringKey(result, report);
+      if (report.material_call && (report.page_index === 0 || report.page_index === undefined)) remember(key, report.material_call);
+      if (key && superseded.has(authoringRevision(key)))
+        return base('requires_source', 'A newly supplied first-page form superseded this authoring revision. Preserve the selected source and obtain its canonical current form; no older binding or cached form is revived.', source + '.report');
+      if (report.complete !== true) {
+        if (report.next_calls?.length) {
+          const next = selectForms(report.next_calls, source + '.report.next_calls', { readOnly: true });
+          return next.state === 'ready' ? { ...next, state: 'read_required',
+            instruction: 'Read this exact next page before authoring. Retain earlier bytes and respect fragment identities; page transport does not prove review. ' + next.instruction } : next;
+        }
+        return base('requires_source', 'The authoring source is incomplete and no exact next-page call was supplied. Do not stage or edit incomplete content.', source + '.report');
+      }
+      if (report.authoring_scope === 'delivery-closeout')
+        return base('idle', 'The bound closeout evidence is complete. Use the current control and evidence for the requested handoff.', source + '.report');
+      let material = report.material_call ?? (key && forms.get(key));
+      if (material && !available(material)) {
+        if (key) forms.delete(key);
+        material = null;
+      }
+      if (material) return selectForms([material], source + (report.material_call ? '.report.material_call' : '.cached_material_call'));
+      if (report.first_page_call) {
+        const next = selectForms([report.first_page_call], source + '.report.first_page_call', { readOnly: true });
+        return next.state === 'ready' ? { ...next, state: 'read_required',
+          instruction: 'No first-page form is retained for this exact manifest. Read the supplied first page; never derive a cursor, reference or new binding. ' + next.instruction } : next;
+      }
+      return base('requires_source', 'No authoring form is available for this exact manifest. Obtain its canonical first page; do not reuse another target, revision or manifest.', source + '.report');
+    }
+    const supplied = [...(result.next_calls ?? []), ...(result.continuation?.next_calls ?? []),
+      ...(report?.next_calls ?? []), ...(result.navigation?.next_calls ?? []), ...(result.family_result?.next_calls ?? [])];
+    if (supplied.length) return selectForms(supplied, source + '.next_calls');
+    const resume = [...(result.resume_call ? [result.resume_call] : []),
+      ...(result.continuation?.resume_call ? [result.continuation.resume_call] : [])];
+    if (resume.length) return selectForms(resume, source + '.resume_call');
+    if ([result, result.continuation, report].filter(object).some(owner => owner.recovery_only?.unavailable_calls?.length))
+      return base('requires_source', 'No normal call could be registered. The exact original requests are retained only in recovery_only; follow original-operation recovery without creating new identities.', source);
+    return base('idle', 'No unique next action was supplied. Follow the canonical current-state instruction; no tool call is inferred.', source);
+  }
+  return Object.freeze({
+    project(domain) {
+      const result = clone(domain);
+      // An adapter may already have loaded one safe page after this result.
+      // Retain the exact outer first-page form before selecting that nested
+      // context; incomplete nested pages still select only their supplied read.
+      rememberAuthoring(result);
+      if (result.terminal === true) result.next_action = terminal(result, 'outer');
+      else if (result.next_read) {
+        const read = result.next_read, nested = read.result;
+        // An explicit null means the exact read could not be retained. Its Raw
+        // execution record remains evidence/recovery, never a normal fallback.
+        const retry = Object.hasOwn(read, 'call') ? read.call : read;
+        if (read.failure?.phase === 'validation') result.next_action = base('requires_source',
+          'The supplied read could not be validated. Preserve the original outcome and receipt; obtain the canonical read source without repeating the write.', 'next_read');
+        else if (nested?.terminal === true) result.next_action = terminal(nested, 'next_read.result');
+        else if (!read.error && read.failed !== true && nested?.outcome === 'inspect_result' && nested.report?.available !== false)
+          result.next_action = fromContext(nested, 'next_read.result');
+        else if (callValue(retry)?.tool === 'agdf_inspect') {
+          const next = selectForms([retry], 'next_read', { readOnly: true });
+          result.next_action = next.state === 'ready' ? { ...next, state: 'read_required',
+            instruction: 'The follow-up read did not produce an available nonterminal result. Retry only this exact read when appropriate; never repeat the outer write. ' + next.instruction } : next;
+        } else result.next_action = base('requires_source', 'The follow-up read failed without an exact supplied read call. Preserve the outer outcome/receipt; do not retry the outer write.', 'next_read');
+      } else result.next_action = fromContext(result, 'outer');
+      result.next_action.context_path = result.next_read?.result ? 'next_read.result' : 'outer';
+      if (result.next_read?.result?.report) result.next_action.instruction +=
+        ' The already loaded source report is response.structuredContent.next_read.result.report. Consume that report without another inspect call.';
+      return result;
+    },
+    close() { forms.clear(); superseded.clear(); },
+  });
+}