create-agdf 0.30.0 → 0.31.0

package/generated/plugins/agdf/mcp/server/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(); },
+  });
+}

package/generated/plugins/agdf/mcp/server/src/prepared-call-transport.js

@@ -0,0 +1,306 @@
+import { createHash, randomUUID } from 'node:crypto';
+
+const writeTools = new Set(['agdf_project', 'agdf_run', 'agdf_prepare', 'agdf_record', 'agdf_approve', 'agdf_revise', 'agdf_closeout']);
+const tools = new Set([...writeTools, 'agdf_inspect']);
+const referencePattern = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/u;
+const WHOLE_PAYLOAD = '/command/payload';
+const referenceSchema = { type: 'object', additionalProperties: false, required: ['prepared_call_id', 'inputs'], properties: {
+  prepared_call_id: { type: 'string', pattern: '^[0-9a-f-]{36}$' },
+  inputs: { type: 'object', maxProperties: 16 },
+} };
+const inputNames = pointers => {
+  const parts = pointers.map(pointer => pointer.split('/').slice(3));
+  const leaves = parts.map(path => path.at(-1) || 'payload');
+  const names = parts.map((path, index) => {
+    const base = /^[a-z_]/u.test(leaves[index]) && leaves.filter(leaf => leaf === leaves[index]).length === 1
+      ? leaves[index] : path.join('_') || 'payload';
+    return /^[a-z_]/u.test(base) ? base : `field_${base}`;
+  });
+  // Flattened paths may collide with literal underscore field names. The
+  // deterministic suffix belongs to this form only, never to a binding or UUID.
+  const reserved = new Set(names), used = new Set();
+  return names.map(base => {
+    let name = base, index = 1;
+    if (names.filter(candidate => candidate === base).length > 1 || used.has(name)) {
+      do { name = `${base}_${index++}`; } while (reserved.has(name) || used.has(name));
+    }
+    used.add(name); return name;
+  });
+};
+
+// Argument storage, never permission or policy. Owned plugin publishers may
+// retain exact templates across connections; ad-hoc servers stay connection-local. The original
+// group, immutable binding, UUID and every Core validator still execute unchanged.
+export function preparedTransportSchema(name, schema) {
+  if (!tools.has(name)) return schema;
+  const { properties, $defs, type, additionalProperties, ...guards } = schema;
+  return { type, additionalProperties, required: [], ...($defs ? { $defs } : {}),
+    properties: { ...properties, ...referenceSchema.properties,
+      ...(name === 'agdf_inspect' ? { inputs: { type: 'object', maxProperties: 0 } }
+        : name === 'agdf_prepare' ? { inputs: { ...referenceSchema.properties.inputs, description: 'Named required fields; ready: {}.' } } : {}) },
+    anyOf: [{ ...guards, not: { anyOf: [...(guards.not ? [guards.not] : []),
+      { required: ['prepared_call_id'] }, { required: ['inputs'] }] } },
+      { required: referenceSchema.required, maxProperties: 2 }],
+  };
+}
+export function createPreparedCallTransport({ now = Date.now, maxEntries = 256, lifetimeMs = 30 * 60_000, validateRead = () => false, store } = {}) {
+  if (typeof validateRead !== 'function') throw Error('prepared_read_validator_invalid');
+  if (store && (typeof store.load !== 'function' || typeof store.register !== 'function')) throw Error('prepared_call_store_unavailable');
+  const rows = new Map(), signatures = new Map(), expired = new Map();
+  let unavailableReason = 'prepared_call_unavailable';
+  const storeError = error => ['runtime_provenance_invalid', 'dispatch_busy', 'prepared_call_store_unavailable'].includes(error?.message)
+    ? error.message : 'prepared_call_store_unavailable';
+  const fail = code => { throw Object.assign(Error(code), { facts: { code, dispatch: 'not_dispatched', field: 'arguments' } }); };
+  function expire() {
+    for (const [id, row] of rows) if (now() - row.created >= lifetimeMs) {
+      rows.delete(id); signatures.delete(row.signature); expired.set(id, now());
+    }
+    // Tombstones distinguish observed expiry from a typo without keeping an
+    // unbounded connection history or retaining the expired raw arguments.
+    while (expired.size > maxEntries) expired.delete(expired.keys().next().value);
+  }
+  function referenceState(id) {
+    if (typeof id !== 'string' || !id) return 'reference_empty';
+    if (!referencePattern.test(id)) return 'reference_invalid';
+    expire();
+    if (store) {
+      try {
+        const retained = store.load(id);
+        if (retained.state === 'available') {
+          const parsed = JSON.parse(retained.value), signature = createHash('sha256').update(retained.value).digest('hex');
+          if (retained.signature !== signature || !Number.isSafeInteger(retained.created) || retained.created < 0
+              || Buffer.byteLength(retained.value) > 65536 || !validTemplate(parsed.call, parsed.required)) throw Error('runtime_provenance_invalid');
+          if (now() - retained.created >= lifetimeMs) return 'reference_expired';
+          if (!rows.has(id) && rows.size >= maxEntries) { unavailableReason = 'prepared_call_unavailable'; return 'reference_unavailable'; }
+          rows.set(id, { call: parsed.call, required: parsed.required, names: inputNames(parsed.required), signature, created: retained.created });
+          signatures.set(signature, id); return 'available';
+        }
+        if (retained.state === 'reference_expired') return 'reference_expired';
+        if (retained.state !== 'reference_unknown') throw Error('runtime_provenance_invalid');
+        return 'reference_unknown';
+      } catch (error) { unavailableReason = storeError(error); return 'reference_unavailable'; }
+    }
+    return rows.has(id) ? 'available' : expired.has(id) ? 'reference_expired' : 'reference_unknown';
+  }
+  const operation = call => call.tool === 'agdf_inspect'
+    ? { kind: 'inspect.read', read_only: true, operation: call.arguments.operation,
+      ...Object.fromEntries(['target_id', 'run_id', 'expected_revision_id',
+        'planning', 'gate', 'presentation_id', 'module', 'cursor']
+        .filter(key => call.arguments[key] !== undefined).map(key => [key, structuredClone(call.arguments[key])])) }
+    : ({ kind: call.arguments.command?.kind ?? null,
+    ...Object.fromEntries(['operation_id', 'target_id', 'run_id', 'expected_revision_id']
+      .filter(key => call.arguments[key] !== undefined).map(key => [key, call.arguments[key]])),
+    ...Object.fromEntries(['gate', 'presentation_id'].filter(key => call.arguments.command?.payload?.[key] !== undefined)
+      .map(key => [key, call.arguments.command.payload[key]])) });
+  function validTemplate(call, required = []) {
+    if (!tools.has(call?.tool) || !call.arguments || typeof call.arguments !== 'object' || Array.isArray(call.arguments)
+        || !Array.isArray(required)) return false;
+    if (call.tool === 'agdf_inspect') {
+      if (required.length || typeof call.arguments.operation !== 'string' || !call.arguments.operation
+          || ['prepared_call_id', 'inputs', 'command'].some(key => Object.hasOwn(call.arguments, key))) return false;
+      // Only the owning server can attest the original read schema and tool's
+      // read-only declaration. This callback never fills missing selectors.
+      try { return validateRead(structuredClone(call)) === true; } catch { return false; }
+    }
+    if (!referencePattern.test(call.arguments.operation_id ?? '')
+        || typeof call.arguments.command?.kind !== 'string' || !call.arguments.command.kind || !Array.isArray(required)
+        || required.length > 16 || new Set(required).size !== required.length
+        // Core asks for the whole payload only when no single variant applies;
+        // it is then the one input, never combined with nested field pointers.
+        || required.includes(WHOLE_PAYLOAD) && required.length !== 1
+        || required.some(p => !/^\/command\/payload(?:\/(?:[a-z_]+|[0-9]+))*$/u.test(p)
+          || p.split('/').some(k => ['__proto__', 'prototype', 'constructor'].includes(k)))) return false;
+    return true;
+  }
+  function originalProjection(raw, fields, names = inputNames(fields)) {
+    return { required_inputs: names, input_fields: names.map(name => ({ name, required: true })), operation: operation(raw), recovery_only: {
+      original_call: structuredClone(raw), required_inputs: [...fields], authorizes: false,
+      input_fields: names.map((name, index) => ({ name, pointer: fields[index] })),
+      instruction: raw.tool === 'agdf_inspect'
+        ? 'Recovery only, never the normal call path. Across reconnect, preserve this exact original read and its target, Run, revision, cursor and original operation-status selection. Never infer a target, refresh a selected revision or replace the original status UUID.'
+        : 'Recovery only, never the normal call path. Preserve this exact original raw call and UUID across reconnect. For an uncertain dispatch, first observe the original operation and retain exactly the inputs already submitted; never refresh the revision, invent a UUID or change the payload to escape uncertainty.' } };
+  }
+  const unregisteredRecovery = (call, required = []) => validTemplate(call, required) ? originalProjection(call, required) : null;
+  function submit(call, required = []) {
+    if (!validTemplate(call, required)) return undefined;
+    const value = JSON.stringify({ call, required });
+    if (Buffer.byteLength(value) > 65536) return undefined;
+    expire();
+    const signature = createHash('sha256').update(value).digest('hex');
+    let id = signatures.get(signature);
+    if (!id) {
+      if (rows.size >= maxEntries) return undefined;
+      let created = now();
+      if (store) {
+        try {
+          const retained = store.register({ value, signature, created });
+          if (!retained) return undefined;
+          if (!referencePattern.test(retained.id ?? '') || !Number.isSafeInteger(retained.created) || retained.created < 0) throw Error('runtime_provenance_invalid');
+          id = retained.id; created = retained.created;
+        } catch (error) { unavailableReason = storeError(error); return undefined; }
+      } else id = randomUUID();
+      signatures.set(signature, id);
+      rows.set(id, { call: JSON.parse(value).call, required: [...required], names: inputNames(required), signature, created });
+    } else if (store && referenceState(id) !== 'available') {
+      return undefined;
+    }
+    return { tool: call.tool, arguments: { prepared_call_id: id, inputs: {} } };
+  }
+  function projectCall(call, required = []) {
+    unavailableReason = 'prepared_call_unavailable';
+    if (!tools.has(call?.tool)) return call;
+    const alreadyPrepared = Object.hasOwn(call.arguments ?? {}, 'prepared_call_id');
+    const saved = alreadyPrepared && referenceState(call.arguments.prepared_call_id) === 'available'
+      ? rows.get(call.arguments.prepared_call_id) : null;
+    if (alreadyPrepared && (!saved || saved.call.tool !== call.tool
+        || Object.keys(call.arguments).some(key => !['prepared_call_id', 'inputs'].includes(key))
+        || !call.arguments.inputs || typeof call.arguments.inputs !== 'object' || Array.isArray(call.arguments.inputs)
+        || call.tool === 'agdf_inspect' && Object.keys(call.arguments.inputs).length)) return null;
+    const raw = saved?.call ?? call, fields = saved?.required ?? required;
+    const prepared = alreadyPrepared ? { tool: call.tool, arguments: structuredClone(call.arguments) } : submit(raw, fields);
+    if (!prepared) return null;
+    const names = [...(saved?.names ?? rows.get(prepared.arguments.prepared_call_id).names)];
+    return { ...prepared, ...originalProjection(raw, fields, names) };
+  }
+  return {
+    // Transport availability only: never a gate, review or permission decision.
+    // An offered input form legitimately has no authored values yet.
+    isAvailable(call) {
+      const args = call?.arguments;
+      if (!tools.has(call?.tool) || !args || typeof args !== 'object'
+          || !Object.hasOwn(args, 'prepared_call_id') || !Object.hasOwn(args, 'inputs')
+          || !args.inputs || typeof args.inputs !== 'object' || Array.isArray(args.inputs)
+          || Object.keys(args).some(key => !['prepared_call_id', 'inputs'].includes(key))
+          || referenceState(args.prepared_call_id) !== 'available') return false;
+      return rows.get(args.prepared_call_id).call.tool === call.tool
+        && (call.tool !== 'agdf_inspect' || Object.keys(args.inputs).length === 0);
+    },
+    decorate: function projectResult(result) {
+      const value = structuredClone(result);
+      // Explicit terminal/uncertain recovery can be resumed on a new connection.
+      // Keep its read requests independent of shared normal-form objects.
+      if (value.recovery && typeof value.recovery === 'object') value.recovery = structuredClone(value.recovery);
+      if (value.next_read?.result) value.next_read.result = projectResult(value.next_read.result);
+      if (value.next_read?.tool === 'agdf_inspect' && value.next_read.arguments) {
+        // tool/arguments are the honest record of the adapter's actual read.
+        // A separate normal retry retains that exact read without retyping it.
+        const raw = { tool: value.next_read.tool, arguments: value.next_read.arguments };
+        const retry = projectCall(raw);
+        value.next_read.call = retry ? { tool: retry.tool, arguments: retry.arguments } : null;
+        const projection = retry ?? unregisteredRecovery(raw);
+        if (projection) for (const key of ['required_inputs', 'input_fields', 'operation', 'recovery_only'])
+          value.next_read[key] = projection[key];
+        if (!retry) value.next_read.transport_reason = unavailableReason;
+      }
+      for (const owner of [value, value.report, value.continuation, value.recovery, value.navigation,
+        value.family_result, value.presentation_delivery, value.next_action].filter(Boolean)) {
+        const unavailable = [];
+        const projectReadyCall = call => {
+          if (owner === value.recovery && call?.tool === 'agdf_inspect') return call;
+          const projected = projectCall(call);
+          if (!projected) {
+            const recovery = unregisteredRecovery(call);
+            if (recovery) unavailable.push({ ...recovery.recovery_only, operation: recovery.operation, transport_reason: unavailableReason });
+          }
+          return projected;
+        };
+        const projectHelpers = container => {
+          for (const key of ['resume_call', 'operation_status_call', 'contract_call', 'first_page_call', 'larger_source_call'])
+            if (container?.[key]) container[key] = projectReadyCall(container[key]);
+        };
+        for (const form of [owner.prepared_call, owner.material_call, owner.approval_call, ...owner.recording_calls ?? []].filter(Boolean)) {
+          if (owner === value.recovery && form.call?.tool === 'agdf_inspect') continue;
+          const raw = form.call, projected = projectCall(raw, form.required_inputs);
+          delete form.submit;
+          if (!tools.has(raw?.tool)) continue;
+          form.call = projected ? { tool: projected.tool, arguments: projected.arguments } : null;
+          if (projected) {
+            form.required_inputs = projected.required_inputs; form.input_fields = projected.input_fields;
+            form.operation = projected.operation; form.recovery_only = projected.recovery_only;
+            form.instruction = (raw.tool === 'agdf_inspect'
+              ? 'Use call.tool with call.arguments unchanged, including inputs:{}. The adapter retains the exact read target and selectors. Do not rebuild an envelope or fill any inputs. recovery_only retains the original read for reconnect; it grants no authority. '
+              : 'Use call.tool with call.arguments. Fill only call.arguments.inputs using the named required_inputs fields; keep its reference unchanged. The adapter maps those names to the exact stored command fields and retains binding and UUID. Do not construct a raw envelope or copy technical JSON paths. Keep authored text as string data using host-supported serialization. Check failure before reading returned fields. recovery_only is separate original-request recovery, never the normal write path. ') + (form.instruction ?? '');
+          } else {
+            const recovery = unregisteredRecovery(raw, form.required_inputs);
+            if (recovery) Object.assign(form, recovery);
+            form.state = 'transport_unavailable'; form.transport_reason = unavailableReason;
+            form.authorizes = false;
+          }
+          projectHelpers(form);
+          projectHelpers(form.content_contract);
+        }
+        if (owner.next_calls) owner.next_calls = owner.next_calls.map(projectReadyCall).filter(Boolean);
+        projectHelpers(owner);
+        projectHelpers(owner.content_contract);
+        if (unavailable.length) owner.recovery_only = { ...owner.recovery_only, authorizes: false,
+          unavailable_calls: [...(owner.recovery_only?.unavailable_calls ?? []), ...unavailable] };
+        for (const call of owner.next_calls ?? []) if (call?.arguments?.prepared_call_id) {
+          call.required_inputs = [];
+          call.submission_instruction = 'This call is complete. Forward arguments unchanged, including inputs:{}. No cloning helper, new reference, UUID or binding is needed. Core still checks current eligibility.';
+        }
+      }
+      // The normal action has exactly the same call shape as named forms and
+      // ready calls; its original raw request stays in the explicit recovery branch.
+      if (value.next_action?.call) {
+        const projected = projectCall(value.next_action.call, value.next_action.required_inputs);
+        if (projected) value.next_action = { ...value.next_action,
+          call: { tool: projected.tool, arguments: projected.arguments }, required_inputs: projected.required_inputs,
+          input_fields: projected.input_fields, operation: projected.operation, recovery_only: projected.recovery_only };
+        else if (tools.has(value.next_action.call?.tool))
+          value.next_action = { ...value.next_action, ...(unregisteredRecovery(value.next_action.call, value.next_action.required_inputs) ?? {}),
+            state: 'transport_unavailable', authorizes: false, transport_reason: unavailableReason, call: null };
+      }
+      return value;
+    },
+    validationHint(name, input) {
+      if (!tools.has(name) || !input || typeof input !== 'object') return '';
+      const id = input.prepared_call_id ?? input.submit_id;
+      const prefix = 'Normal call arguments contain only prepared_call_id and inputs. Copy the supplied call.arguments; never submit_id, a new ID or duplicated raw fields. ';
+      if (typeof id !== 'string') {
+        if (!Object.hasOwn(input, 'inputs')) return '';
+        const raw = Object.keys(input).some(key => !['inputs', 'prepared_call_id', 'submit_id'].includes(key));
+        return prefix + (raw ? 'A full raw call cannot contain inputs. ' : 'The prepared reference is missing. ')
+          + 'Fill only its named required_inputs fields. Raw requests belong only to the explicit recovery path. No operation was dispatched.';
+      }
+      const state = referenceState(id);
+      if (state === 'reference_unavailable') return 'The owned reference store is unavailable or could not establish its integrity. Preserve the original receipt and saved request; no operation was dispatched by this attempt.';
+      if (state !== 'available') return state === 'reference_expired'
+        ? 'The supplied reference was issued previously and its original lifetime has expired. Use saved original-request/UUID observation and recovery; never generate another binding or UUID. No operation was dispatched.'
+        : state === 'reference_empty' ? 'The prepared reference is empty. Copy the existing reference in the supplied call.arguments; never use an empty placeholder. No operation was dispatched.'
+          : state === 'reference_invalid' ? 'The prepared reference is malformed. Copy the supplied call.arguments unchanged; never retype or autocorrect a reference. No operation was dispatched.'
+            : 'The reference is unknown on this connection; this is not proof of expiry. Copy the exact supplied call.arguments or use saved original-request/UUID recovery. Never guess or autocorrect. No operation was dispatched.';
+      const row = rows.get(id);
+      if (row.call.tool !== name) return 'A prepared reference cannot cross permission groups. No operation was dispatched.';
+      const conflict = Object.entries(input).some(([key, value]) => !['prepared_call_id', 'submit_id', 'inputs'].includes(key)
+        && JSON.stringify(row.call.arguments[key]) !== JSON.stringify(value));
+      if (conflict) return 'Do not merge raw and prepared calls: their fixed fields conflict. Review the intended binding; neither binding was executed.';
+      return (prefix + (row.required.length
+        ? `Fill exactly these named inputs from actual author/review/reply data: ${JSON.stringify(row.names)}. Do not invent values or mix named and legacy pointer inputs.`
+        : `Exact ready call: ${JSON.stringify({ tool: name, arguments: { prepared_call_id: id, inputs: {} } })}`)).slice(0, 768);
+    },
+    resolve(name, input) {
+      if (!Object.hasOwn(input, 'prepared_call_id')) return input;
+      const state = referenceState(input.prepared_call_id);
+      if (state !== 'available') return fail(state === 'reference_expired' ? 'session_expired'
+        : state === 'reference_unknown' ? 'prepared_call_unknown'
+          : state === 'reference_unavailable' ? unavailableReason === 'prepared_call_unavailable' ? 'resource_limit' : unavailableReason
+            : 'command_schema_invalid');
+      const row = rows.get(input.prepared_call_id);
+      if (row.call.tool !== name || Object.keys(input).some(k => !['prepared_call_id', 'inputs'].includes(k))
+          || !input.inputs || typeof input.inputs !== 'object' || Array.isArray(input.inputs)
+          || Buffer.byteLength(JSON.stringify(input)) > 65536) return fail('command_schema_invalid');
+      const keys = Object.keys(input.inputs);
+      const named = keys.length === row.names.length && row.names.every(key => Object.hasOwn(input.inputs, key));
+      const legacy = keys.length === row.required.length && row.required.every(key => Object.hasOwn(input.inputs, key));
+      if (!named && !legacy) return fail('command_schema_invalid');
+      const args = structuredClone(row.call.arguments);
+      for (const [index, pointer] of row.required.entries()) {
+        const parts = pointer.slice(1).split('/'); let destination = args;
+        for (const part of parts.slice(0, -1)) destination = destination[part];
+        destination[parts.at(-1)] = structuredClone(input.inputs[named ? row.names[index] : pointer]);
+      }
+      return args;
+    },
+    close() { rows.clear(); signatures.clear(); expired.clear(); },
+  };
+}

package/generated/plugins/agdf/mcp/server/src/safe-read-continuation.js

@@ -0,0 +1,62 @@
+// Only a single, exact Core-supplied inspect call may be folded into a response.
+// Dispatch can repair sealed relationships; no dispatch or command is auto-run.
+const operations = new Set(['authoring-inputs', 'gate-check', 'operation-contract']);
+// Only read results fold a follow-up read. A write result returns at once so a
+// slow or large follow-up can never delay or enlarge the receipt of a committed
+// write; its next read stays a normal supplied call.
+const readableOutcome = new Set(['inspect_result', 'skill_continuation', 'intake_continuation', 'control_result']);
+
+export function suppliedReadContinuation(result) {
+  if (!result || result.terminal === true || !readableOutcome.has(result.outcome)) return null;
+  if (result.outcome === 'inspect_result' && result.report?.available === false) return null;
+  // Source pages are consumed explicitly, in order. Folding page N+1 into page N
+  // would create two competing source locations and could lose the first form.
+  if (result.operation === 'authoring-inputs') return null;
+  // Bootstrap state and initialization have compact response contracts. Their
+  // supplied setup/Run operation-contract remains an explicit next action
+  // instead of duplicating the full command schema inside the bootstrap result.
+  if (result.operation === 'project-state' || result.binding?.kind === 'project.initialize') return null;
+  // These are authoritative normal next steps, not recovery or optional preview.
+  const lists = [result.next_calls, result.continuation?.next_calls,
+    result.report?.next_calls, result.family_result?.next_calls].filter(Array.isArray);
+  const candidates = new Map(lists.flat().filter(Boolean).map(call => [JSON.stringify([call.tool, call.arguments]), call]));
+  if (candidates.size !== 1) return null;
+  const call = [...candidates.values()][0];
+  if (call.tool !== 'agdf_inspect' || !operations.has(call.arguments?.operation)
+    || call.arguments?.planning && call.arguments?.run_id) return null;
+  return { tool: call.tool, arguments: structuredClone(call.arguments) };
+}
+
+export async function appendSafeReadContinuation(result, { execute, validate, allowed = true } = {}) {
+  let call, phase = 'selection';
+  // execute owns normal parsing, policy and result validation. A follow-up failure
+  // is separate from the original read result and never replaces it.
+  try {
+    call = allowed && suppliedReadContinuation(result);
+    if (!call) return result;
+    phase = 'validation';
+    if (!validate?.(call)) return result;
+    phase = 'execute';
+    const observed = await execute(call);
+    return { ...result, next_read: { ...call, result: observed, authorizes: false } };
+  } catch {
+    if (!call) return result;
+    return { ...result, next_read: { ...call, result: null, authorizes: false,
+      failure: { code: 'read_followup_unavailable', phase, original_effect_unchanged: true,
+        instruction: 'The original operation result and receipt remain authoritative. No write was repeated. Inspect the supplied read separately; never replay a successful write to obtain its next step.' } } };
+  }
+}
+
+// Core validates the original domain before this explicit MCP wire projection.
+// Open result schemas already permit the additive fields; dispatch is closed.
+export function nextActionOutputSchema(name, schema) {
+  if (name !== 'agdf_dispatch' || !schema) return schema;
+  return { ...schema, properties: { ...schema.properties,
+    next_action: { type: 'object', required: ['state', 'authorizes'],
+      properties: { state: { type: 'string' }, authorizes: { const: false } } },
+    next_read: { type: 'object', required: ['tool', 'arguments', 'result', 'authorizes'],
+      properties: { tool: { const: 'agdf_inspect' }, arguments: { type: 'object' },
+        result: { type: ['object', 'null'] }, authorizes: { const: false } } },
+    recovery_only: { type: 'object' },
+  } };
+}