chati-dev 4.5.28 → 4.5.29

package/src/orchestrator/clickup-mcp-observer.js

@@ -0,0 +1,226 @@
+import { canonicalSerialize, sha256 } from '@chati/core';
+import { openClickUpMcpClient } from '../installer-v2/clickup-mcp-client.js';
+import { delegatedAuthorityPublicIdentity, signDelegatedClickUpMcpPayload } from '../installer-v2/installation-authority.js';
+import { loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
+import { readProjectClickUpOutbox } from './clickup-projection.js';
+import {
+  acknowledgeClickUpProjection, assertClickUpMcpAuthorityIdentity,
+  prepareClickUpProjectionDelivery, resolveClickUpProjectionLookup, signedClickUpMcpResultPayload,
+} from './clickup-runtime.js';
+
+const BEGIN = 'CHATI-RAIL-V1-BEGIN';
+const END = 'CHATI-RAIL-V1-END';
+const LIMIT = 64 * 1024;
+const STATUS = Object.freeze({ in_progress: 'in progress', ready_to_merge: 'feedback', done: 'done' });
+function fail(code = 'CLICKUP_OBSERVATION_INVALID') {
+  throw Object.assign(new Error('ClickUp observation is unconfirmed; no automatic resend is permitted'), { code });
+}
+function object(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function exact(value, keys) { return object(value) && Object.keys(value).sort().join(',') === [...keys].sort().join(','); }
+
+/** One unambiguous JSON tool result. Remote prose/errors never enter receipts. */
+export function parseClickUpToolResult(result) {
+  if (!object(result) || result.isError === true) fail();
+  const texts = result.content?.filter(item => item.type === 'text') || [];
+  let textValue;
+  try { if (texts.length === 1) textValue = JSON.parse(texts[0].text); } catch { fail(); }
+  if (texts.length > 1 || (!object(result.structuredContent) && !object(textValue))) fail();
+  if (result.structuredContent !== undefined && (!object(result.structuredContent)
+    || (textValue !== undefined && canonicalSerialize(textValue) !== canonicalSerialize(result.structuredContent)))) fail();
+  return result.structuredContent || textValue;
+}
+
+// Validate the small, discovered schema subset used by this observer. Unknown
+// validation keywords fail closed instead of silently ignoring new constraints.
+function schemaValue(schema, value) {
+  if (!object(schema) || Object.keys(schema).some(key => !['type', 'description', 'title', 'enum', 'pattern', 'items'].includes(key))) fail('CLICKUP_TOOL_SCHEMA_CHANGED');
+  if (schema.type === 'string') {
+    if (typeof value !== 'string' || (schema.pattern !== undefined && (schema.pattern !== '^\\d+$' || !/^\d+$/.test(value)))) fail('CLICKUP_TOOL_SCHEMA_CHANGED');
+  } else if (schema.type === 'array') {
+    if (!Array.isArray(value) || !schema.items) fail('CLICKUP_TOOL_SCHEMA_CHANGED');
+    for (const item of value) schemaValue(schema.items, item);
+  } else fail('CLICKUP_TOOL_SCHEMA_CHANGED');
+  if (schema.enum !== undefined && (!Array.isArray(schema.enum) || !schema.enum.includes(value))) fail('CLICKUP_TOOL_SCHEMA_CHANGED');
+}
+function toolArguments(tools, name, args) {
+  const schema = tools.find(tool => tool.name === name)?.inputSchema;
+  if (!object(schema) || schema.type !== 'object' || !object(schema.properties)
+    || Object.keys(schema).some(key => !['$schema', 'type', 'properties', 'required', 'additionalProperties', 'description', 'title'].includes(key))
+    || (schema.required !== undefined && (!Array.isArray(schema.required) || schema.required.some(key => !Object.hasOwn(args, key))))
+    || (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== 'boolean')) fail('CLICKUP_TOOL_SCHEMA_CHANGED');
+  for (const [key, value] of Object.entries(args)) schemaValue(schema.properties[key], value);
+  return args;
+}
+
+function statusFor(projection) {
+  const status = projection.payload?.status;
+  if (!Object.hasOwn(STATUS, status ?? '') || !['update', 'close'].includes(projection.operation)
+    || ((projection.operation === 'close') !== (status === 'done'))) fail('CLICKUP_PROJECTION_UNSUPPORTED');
+  return STATUS[status];
+}
+function recordFor(projection) {
+  return { projection_id: projection.projection_id, idempotency_key: projection.idempotency_key,
+    operation: projection.operation, delivery_attempt: projection.attempts,
+    delivery_attempted_at: projection.last_attempt_at, payload: projection.payload,
+    payload_digest: sha256(projection.payload), remote_status: statusFor(projection) };
+}
+function validateRecord(record) {
+  if (!exact(record, ['projection_id', 'idempotency_key', 'operation', 'delivery_attempt', 'delivery_attempted_at', 'payload', 'payload_digest', 'remote_status'])
+    || !object(record.payload) || typeof record.projection_id !== 'string' || typeof record.idempotency_key !== 'string'
+    || !Number.isSafeInteger(record.delivery_attempt) || record.delivery_attempt < 1
+    || typeof record.delivery_attempted_at !== 'string' || !Number.isFinite(Date.parse(record.delivery_attempted_at))
+    || sha256(record.payload) !== record.payload_digest || statusFor(record) !== record.remote_status) fail();
+}
+
+/** Preserve full returned Markdown outside one managed section. No truncation. */
+export function readClickUpManagedSection(description, { project_id, clickup_ref }) {
+  if (typeof description !== 'string' || Buffer.byteLength(description) > LIMIT) fail('CLICKUP_DESCRIPTION_UNAVAILABLE');
+  const start = description.indexOf(BEGIN); const end = description.indexOf(END);
+  if (start === -1 && end === -1) return { prefix: description, suffix: '', document: null };
+  if (start === -1 || end < start || description.indexOf(BEGIN, start + BEGIN.length) !== -1
+    || description.indexOf(END, end + END.length) !== -1
+    || (start !== 0 && description[start - 1] !== '\n')
+    || (end + END.length !== description.length && description[end + END.length] !== '\n')) fail();
+  const segment = description.slice(start + BEGIN.length, end);
+  const match = /^\n\n```(?:json)?\n([^\n]+)\n```\n\n$/.exec(segment);
+  let document;
+  try { if (match) document = JSON.parse(match[1]); } catch { fail(); }
+  if (!exact(document, ['schema_version', 'project_id', 'clickup_ref', 'preserved_text_digest', 'records'])
+    || document.schema_version !== 1 || document.project_id !== project_id || document.clickup_ref !== clickup_ref
+    || !Array.isArray(document.records) || !document.records.length || document.records.length > 100) fail();
+  for (const record of document.records) validateRecord(record);
+  if (new Set(document.records.map(record => record.projection_id)).size !== document.records.length
+    || new Set(document.records.map(record => record.idempotency_key)).size !== document.records.length) fail();
+  const prefix = description.slice(0, start); const suffix = description.slice(end + END.length);
+  if (document.preserved_text_digest !== sha256({ prefix, suffix })) fail('CLICKUP_DESCRIPTION_DRIFT');
+  return { prefix, suffix, document };
+}
+
+export function buildClickUpManagedDescription(description, projection, project_id) {
+  const current = readClickUpManagedSection(description, { project_id, clickup_ref: projection.clickup_ref });
+  const record = recordFor(projection); validateRecord(record);
+  const records = current.document?.records || [];
+  // Reusing an existing marker is only a lookup, never another mutation.
+  if (records.some(item => item.projection_id === record.projection_id || item.idempotency_key === record.idempotency_key)) fail('CLICKUP_RECORD_ALREADY_PRESENT');
+  const prefix = current.document ? current.prefix : `${current.prefix}${current.prefix ? '\n\n' : ''}`;
+  const suffix = current.suffix;
+  const document = { schema_version: 1, project_id, clickup_ref: projection.clickup_ref,
+    preserved_text_digest: sha256({ prefix, suffix }), records: [...records, record] };
+  const markdown = `${prefix}${BEGIN}\n\n\`\`\`json\n${canonicalSerialize(document)}\n\`\`\`\n\n${END}${suffix}`;
+  if (document.records.length > 100 || Buffer.byteLength(markdown) > LIMIT) fail('CLICKUP_DESCRIPTION_TOO_LARGE');
+  return markdown;
+}
+
+function ownedTask(result, ownership, destination) {
+  const data = parseClickUpToolResult(result);
+  // A well-formed, error-free lookup that describes no task at all is a
+  // positive confirmation of absence, not an ambiguous mismatch. Only this
+  // structural signal may ever downgrade to not_found; a task that exists but
+  // fails an ownership field, or a call that erred, stays unknown.
+  if (Object.keys(data).length === 0) fail('CLICKUP_TASK_NOT_FOUND');
+  const task = data.task || data;
+  if (task.id !== ownership.task_id || task.name !== ownership.name || task.list?.id !== destination.list_id
+    || (task.team_id !== undefined && String(task.team_id) !== destination.workspace_id)
+    || typeof task.markdown_description !== 'string' || !task.markdown_description.includes(ownership.sentinel)
+    || typeof task.status?.status !== 'string' || task.description_truncated === true) fail('CLICKUP_TASK_OWNERSHIP_UNCONFIRMED');
+  return task;
+}
+
+export function verifyClickUpManagedObservation(task, projection, project_id) {
+  const section = readClickUpManagedSection(task.markdown_description, { project_id, clickup_ref: projection.clickup_ref });
+  const expected = recordFor(projection);
+  // The active record must also be the last one, so a later state cannot be
+  // mistaken for this delivery merely because an older marker still exists.
+  if (!section.document || canonicalSerialize(section.document.records.at(-1)) !== canonicalSerialize(expected)
+    || task.status.status !== expected.remote_status) fail();
+  return { success: true, task_id: task.id, list_id: task.list.id, status: task.status.status,
+    record_digest: sha256(expected), description_digest: sha256(task.markdown_description),
+    preserved_text_digest: section.document.preserved_text_digest };
+}
+
+/** Finite host-controller boundary for explicitly owned, single-writer tasks.
+ * Never accepts caller-supplied payloads, remote outcomes, keys or signatures.
+ * No CAS is available upstream: concurrent human editing is NOT supported by
+ * this initial route. ownership must identify the controller's prepared task.
+ */
+export async function deliverClickUpMcpProjection({ projectDir, projection_id, connectionId, ownership,
+  authorityDirectory, clock = () => new Date(), fetchImpl = globalThis.fetch } = {}) {
+  if (!exact(ownership, ['task_id', 'name', 'sentinel']) || !/^[A-Za-z0-9_-]{1,128}$/.test(ownership.task_id)
+    || typeof ownership.name !== 'string' || !ownership.name || typeof ownership.sentinel !== 'string'
+    || ownership.sentinel.length < 32) fail('CLICKUP_TASK_OWNERSHIP_REQUIRED');
+  ownership = { ...ownership };
+  const artifact = loadRuntimeInstallationV2(projectDir, { clock });
+  if (!artifact) fail('V2_INSTALLATION_REQUIRED');
+  const options = { projectDir, projectId: artifact.project_id, kind: 'clickup-mcp', authorityDirectory };
+  const identity = delegatedAuthorityPublicIdentity(options);
+  assertClickUpMcpAuthorityIdentity({ projectDir, identity, clock });
+  const read = () => {
+    const all = readProjectClickUpOutbox({ projectDir, clock }).projections || [];
+    const index = all.findIndex(item => item.projection_id === projection_id);
+    const projection = all[index];
+    if (!projection || projection.clickup_ref !== `clickup://task/${ownership.task_id}`) fail('CLICKUP_TASK_OWNERSHIP_UNCONFIRMED');
+    if (all.slice(0, index).some(item => item.clickup_ref === projection.clickup_ref && item.delivery_state !== 'confirmed')) fail('CLICKUP_EARLIER_PROJECTION_UNCONFIRMED');
+    statusFor(projection);
+    return projection;
+  };
+  let projection = read();
+  if (projection.delivery_state === 'confirmed') return { required_action: 'already_confirmed', projection_id, mutation_attempted: false };
+  if (!['pending', 'sent_unconfirmed', 'retryable_failure'].includes(projection.delivery_state)) fail('CLICKUP_PROJECTION_UNSUPPORTED');
+  const handoff_id = /^rail-handoff:\/\/([^/]+)\//.exec(projection.handoff_ref || '')?.[1];
+  if (!handoff_id) fail();
+  const client = await openClickUpMcpClient({ connectionId, authorityDirectory, fetchImpl, clock: () => new Date(clock()).getTime() });
+  let mutationAttempted = false;
+  try {
+    const tools = await client.listTools();
+    const destination = client.destination;
+    const getArgs = toolArguments(tools, 'clickup_get_task', { task_id: ownership.task_id, include: ['description'], workspace_id: destination.workspace_id });
+    const observe = async () => ownedTask(await client.callTool('clickup_get_task', getArgs), ownership, destination);
+    if (projection.delivery_state === 'pending') {
+      const listArgs = toolArguments(tools, 'clickup_get_list', { list_id: destination.list_id, workspace_id: destination.workspace_id });
+      const data = parseClickUpToolResult(await client.callTool('clickup_get_list', listArgs));
+      const list = data.list || data;
+      if (list.id !== destination.list_id || !Array.isArray(list.statuses)
+        || !list.statuses.some(item => item.status === statusFor(projection))) fail('CLICKUP_STATUS_UNAVAILABLE');
+      const before = await observe();
+      // Validate full Markdown, payload size and discovered mutation schema before
+      // recording an attempt. Then re-read canonical order and prepare atomically.
+      const preview = buildClickUpManagedDescription(before.markdown_description,
+        { ...projection, attempts: projection.attempts + 1, last_attempt_at: new Date(clock()).toISOString() }, artifact.project_id);
+      toolArguments(tools, 'clickup_update_task', { task_id: ownership.task_id, markdown_description: preview,
+        status: statusFor(projection), workspace_id: destination.workspace_id });
+      projection = read();
+      const prepared = prepareClickUpProjectionDelivery({ projectDir, projection_id, clock });
+      if (prepared.required_action === 'already_confirmed') return { required_action: 'already_confirmed', projection_id, mutation_attempted: false };
+      projection = read();
+      if (prepared.required_action === 'send_once_then_ack_or_lookup') {
+        const markdown = buildClickUpManagedDescription(before.markdown_description, projection, artifact.project_id);
+        mutationAttempted = true;
+        try {
+          // Even a positive tool response does not establish business success.
+          await client.callTool('clickup_update_task', { task_id: ownership.task_id, markdown_description: markdown,
+            status: statusFor(projection), workspace_id: destination.workspace_id });
+        } catch { /* An uncertain send can only be followed by readback. */ }
+      }
+    }
+    let response;
+    try { response = { ...verifyClickUpManagedObservation(await observe(), projection, artifact.project_id), workspace_id: destination.workspace_id }; }
+    catch (error) {
+      // Only a positively empty lookup proves the task is gone and safe to
+      // re-send; every other observation failure (schema mismatch, transport
+      // error, ownership mismatch) stays undecidable and must not resend.
+      const state = error?.code === 'CLICKUP_TASK_NOT_FOUND' ? 'not_found' : 'unknown';
+      response = { success: false, state, task_id: ownership.task_id, workspace_id: destination.workspace_id, list_id: destination.list_id };
+    }
+    const kind = mutationAttempted && response.success ? 'clickup_ack' : 'clickup_lookup';
+    const envelope = { schema_version: 2, issuer_id: identity.issuer_id, kind, projection_id,
+      clickup_ref: projection.clickup_ref, idempotency_key: projection.idempotency_key, operation: projection.operation,
+      delivery_attempt: projection.attempts, delivery_attempted_at: projection.last_attempt_at,
+      observed_at: new Date(clock()).toISOString(), response };
+    const signed = { ...envelope, ...signDelegatedClickUpMcpPayload(signedClickUpMcpResultPayload(envelope), options) };
+    const result = kind === 'clickup_ack'
+      ? acknowledgeClickUpProjection({ projectDir, handoff_id, projection_id, receipt: signed, clock })
+      : resolveClickUpProjectionLookup({ projectDir, handoff_id, projection_id, result: signed, clock });
+    return { required_action: response.success ? 'confirmed' : 'lookup_only', projection_id,
+      mutation_attempted: mutationAttempted, delivery_state: result.delivery_state };
+  } finally { await client.close(); }
+}

package/src/orchestrator/clickup-runtime.js

@@ -72,32 +72,43 @@ export function describePreparedClickUpDelivery(prepared) {
   });
 }
 
-/** Atomically marks new sends uncertain before returning any remote payload. */
+/** Prepare exactly one canonical item immediately before its authorized send. */
+export function prepareClickUpProjectionDelivery({ projectDir, projection_id, clock = () => new Date() } = {}) {
+  if (typeof projection_id !== 'string' || !projection_id.trim()) {
+    throw Object.assign(new Error('projection_id must be a non-empty string'), { code: 'INVALID_PROJECTION_ID' });
+  }
+  const outbox = readProjectClickUpOutbox({ projectDir, clock });
+  const projection = outbox.projections?.find((candidate) => candidate.projection_id === projection_id);
+  if (!projection) throw Object.assign(new Error(`projection ${projection_id} does not exist`), { code: 'PROJECTION_NOT_FOUND' });
+  if (['sent_unconfirmed', 'retryable_failure'].includes(projection.delivery_state)) {
+    return Object.freeze({
+      projection_id: projection.projection_id,
+      clickup_ref: projection.clickup_ref,
+      idempotency_key: projection.idempotency_key,
+      delivery_state: projection.delivery_state,
+      delivery_attempt: projection.attempts,
+      delivery_attempted_at: projection.last_attempt_at,
+      required_action: 'lookup_before_resend',
+    });
+  }
+  const handoff_id = projectionHandoffId(projection);
+  const { handoff } = loadRailHandoff({ projectDir, handoff_id });
+  const records = createProjectRailEngine({ projectDir, clock }).records;
+  const tracking = createClickUpTrackingFromState({
+    projectDir, handoff, records, task_id: projection.task_id, clock,
+  });
+  // The core refreshes under its lock. A concurrent sender cannot get another
+  // payload; a concurrent acknowledgement returns already_confirmed instead.
+  const prepared = tracking.prepareExternalDelivery({ projection_id });
+  return describePreparedClickUpDelivery(prepared);
+}
+
+/** Compatibility batch preparation. No transport is invoked by either API. */
 export function preparePendingClickUpProjections({ projectDir, clock = () => new Date() } = {}) {
   const pending = listPendingClickUpProjections({ projectDir, clock });
-  return Object.freeze(pending.map((item) => {
-    if (item.delivery_state !== 'pending') {
-      return Object.freeze({
-        projection_id: item.projection_id,
-        clickup_ref: item.clickup_ref,
-        idempotency_key: item.idempotency_key,
-        delivery_state: item.delivery_state,
-        delivery_attempt: item.delivery_attempt,
-        delivery_attempted_at: item.delivery_attempted_at,
-        required_action: 'lookup_before_resend',
-      });
-    }
-    const outbox = readProjectClickUpOutbox({ projectDir, clock });
-    const projection = outbox.projections.find((candidate) => candidate.projection_id === item.projection_id);
-    const handoff_id = projectionHandoffId(projection);
-    const { handoff } = loadRailHandoff({ projectDir, handoff_id });
-    const records = createProjectRailEngine({ projectDir, clock }).records;
-    const tracking = createClickUpTrackingFromState({
-      projectDir, handoff, records, task_id: projection.task_id, clock,
-    });
-    const prepared = tracking.prepareExternalDelivery({ projection_id: projection.projection_id });
-    return describePreparedClickUpDelivery(prepared);
-  }));
+  return Object.freeze(pending.map((item) => prepareClickUpProjectionDelivery({
+    projectDir, projection_id: item.projection_id, clock,
+  })));
 }
 
 const SENSITIVE_RECEIPT_KEY = /(authorization|cookie|credential|password|secret|token)/i;
@@ -246,6 +257,16 @@ export function loadProjectClickUpMcpAuthority({ projectDir, clock = () => new D
   });
 }
 
+/** Refuse a mismatched delegated signer BEFORE any external mutation. */
+export function assertClickUpMcpAuthorityIdentity({ projectDir, identity, clock = () => new Date() } = {}) {
+  const verifier = loadProjectClickUpMcpAuthority({ projectDir, clock });
+  const capability = CLICKUP_VERIFIER_CAPABILITIES.get(verifier);
+  if (identity?.issuer_id !== capability?.issuer_id
+    || identity?.public_key !== capability?.key.export({ type: 'spki', format: 'pem' })) {
+    throw Object.assign(new Error('ClickUp observer identity does not match the enrolled authority'), { code: 'CLICKUP_OBSERVER_IDENTITY_MISMATCH' });
+  }
+}
+
 export function sanitizeClickUpReceipt(value, depth = 0) {
   if (depth > 8) return '[truncated]';
   if (Array.isArray(value)) return value.slice(0, 100).map((item) => sanitizeClickUpReceipt(item, depth + 1));