@axiom-lattice/core 4.2.2 → 4.2.3

package/dist/index.mjs

@@ -10070,8 +10070,8 @@ var metricsPlugin = {
     type: "metrics",
     category: "data",
     capabilityBundleEligible: true,
-    name: "Metrics",
-    description: "Provides metrics querying capabilities",
+    name: "Metrics (DEPRECATED)",
+    description: "DEPRECATED \u2014 use the 'semantic-metrics' plugin instead. Legacy metrics querying over the old server contract; kept for backward compatibility with existing agents. New agents should enable 'semantic-metrics' (connection-backed, /api/v1, table-grant scoping, semantic meta publishing).",
     tools: [
       { name: "list_datasources", description: "List all datasources from all configured servers" },
       { name: "query_metrics_list", description: "Query available metrics from datasources" },
@@ -22990,6 +22990,14 @@ Do not update or change a belief without new evidence. Every update cites the
 observation, states how it supports or contradicts the Claim, and records the
 resulting Decision Impact or explains why the plan remains unchanged.
 
+An approved scope or criteria change is one reconciliation, not two updates:
+revise \`## Objective\` / \`## Acceptance Criteria\` and, in the same
+reconciliation, re-base every affected Belief Key \u2014 its new Basis must cite the
+user approval \u2014 cancel or replace subtasks that depended on the superseded
+scope, and revise eval coverage to the revised contract. A downgraded
+probability after a scope change is an honest reset, not a regression; continue
+only from the re-based Belief State.
+
 The current runtime requires numeric \`beliefImpact.after\` values and the
 canonical compatibility table below. Treat \`after\` as the evidence support
 percentage for the Claim. It is not an Eval score, Agent quality metric, or Task
@@ -23051,6 +23059,15 @@ that can change the parent goal, acceptance judgment, or next action. It is not
 tool call. Reading a skill, running one command, calling SQL, or editing a file is
 normally an internal \`write_todos\` step.
 
+Persist the plan before executing it. Announcing work in conversation (for
+example, "I will create three sub-agents") is not a plan: before that work
+starts, the parent Belief State must already exist and every planned child must
+be persisted with its contract (\`pending\` until its phase starts,
+\`in_progress\` when it starts). The persisted decomposition is what the user
+aligns on \u2014 in normal approval flows, present the decomposition (children,
+Targets, and belief dimensions) and confirm it before executing it; a deviation
+from the approved design is a material boundary requiring renewed confirmation.
+
 Before creating a subtask, identify: (1) the uncertain parent Belief Key, (2) why
 it affects a decision, (3) the observable evidence this subtask will produce, and
 (4) the Prediction contract with positive and negative result branches and their
@@ -24680,6 +24697,9 @@ For a new Orchestra parent \u2014 build the delegation tree before the parent:
 each sub-agent is a bounded specialist with a clear interface (input/output/responsibility).
 A sub-agent qualifies as a sub-agent when it has independent tools, its own skill, or
 needs separate eval. Do not create a sub-agent for a simple inline step.
+Persist the approved delegation tree as planned child tasks with contracts and
+\`Targets\` before creating any sub-agent ([[task-tracking]]); in normal approval
+flows the decomposition is presented for user confirmation first.
 
 **2. Build each sub-agent's skill first.** Per sub-agent:
 - If domain knowledge exists \u2192 load [[document-learning-learn-capability]]
@@ -32353,7 +32373,7 @@ function snapshotDate(value) {
 
 // src/services/TaskLifecycleService.ts
 import { createHash as createHash6 } from "crypto";
-import { parseTaskBeliefState as parseTaskBeliefState2, snapshotExactArray as snapshotExactArray3, snapshotExactRecord as snapshotExactRecord8, taskBeliefStatesEqual } from "@axiom-lattice/protocols";
+import { parseTaskBeliefState as parseTaskBeliefState2, replaceTaskBeliefState, snapshotExactArray as snapshotExactArray3, snapshotExactRecord as snapshotExactRecord8, taskBeliefStatesEqual } from "@axiom-lattice/protocols";
 
 // src/middlewares/taskBelief.ts
 import { createHash as createHash5 } from "crypto";
@@ -32450,6 +32470,71 @@ function buildParentBeliefActivity(input) {
 function failure2(code, error, hint) {
   return { success: false, code, error, ...hint === void 0 ? {} : { hint } };
 }
+async function seedBeliefOwnerTable(taskStore, owner, impacts) {
+  if (impacts.length === 0) return { description: owner.description ?? "" };
+  const parsed = parseTaskBeliefState2(owner.description ?? "");
+  if (!parsed.success && parsed.code !== "MISSING_BELIEF_STATE") {
+    return failure2("INVALID_BELIEF_TABLE", parsed.message);
+  }
+  const entries = parsed.success ? [...parsed.state.entries] : [];
+  const known = new Set(entries.map((entry) => entry.key));
+  const missing = impacts.filter((impact) => !known.has(impact.key));
+  if (missing.length === 0) return { description: owner.description ?? "" };
+  for (const impact of missing) {
+    entries.push({ key: impact.key, probability: impact.after, target: impact.after, basis: impact.basis });
+  }
+  const base = owner.description ?? "";
+  const description = replaceTaskBeliefState(base, { entries });
+  const updated = await taskStore.update(owner.tenantId, owner.id, { description });
+  if (!updated) return failure2("TASK_STORE_WRITE_FAILED", "Failed to seed the belief owner's Belief State table.");
+  return { description: updated.description ?? description };
+}
+function beliefValidationFailure(validation) {
+  switch (validation.code) {
+    case "MISSING_BELIEF_TABLE":
+      return failure2(
+        validation.code,
+        "The belief owner's description has no '## Belief State' table.",
+        "Initialize a '## Belief State' section in the belief owner task's description via manage_task update, using the canonical four-column table | Belief Key | Probability | Target | Basis |, then retry completion with beliefImpact keys from that table."
+      );
+    case "INVALID_BELIEF_TABLE":
+      return failure2(
+        validation.code,
+        `The belief owner's Belief State table is invalid: ${validation.message}`,
+        "Fix the Belief State table via manage_task update on the belief owner task, then retry completion."
+      );
+    case "INVALID_BELIEF_KEY":
+      return failure2(
+        validation.code,
+        `Belief key '${validation.key}' is not in the belief owner's Belief State table.`,
+        "Add the key to the belief owner's Belief State table via manage_task update, or report an existing key."
+      );
+    case "INVALID_BELIEF_VALUE":
+      return failure2(
+        validation.code,
+        `Belief key '${validation.key}' has an invalid after value.`,
+        "after must be an integer between 0 and 100."
+      );
+    case "INVALID_BELIEF_BASIS":
+      return failure2(
+        validation.code,
+        `Belief key '${validation.key}' has an invalid basis.`,
+        "basis must be a single nonblank line of at most 1000 characters."
+      );
+    case "INVALID_DUPLICATE_BELIEF_KEY":
+      return failure2(
+        validation.code,
+        `Duplicate belief key '${validation.key}'.`,
+        "Report each belief key at most once."
+      );
+    case "MISSING_BELIEF_IMPACT":
+      return failure2(
+        validation.code,
+        "Agent task completion requires beliefImpact.",
+        "Provide beliefImpact: [{ key: '<belief-key>', after: <0-100>, basis: '<evidence>' }]"
+      );
+  }
+}
 function isProjectLifecycleTask(task) {
   const source = task.context?.source;
   return typeof task.workspaceId === "string" && task.workspaceId.length > 0 && typeof task.projectId === "string" && task.projectId.length > 0 && task.workspaceId !== "default" && task.projectId !== "default" && (source === "project_room" || source === "project_task");
@@ -32469,15 +32554,10 @@ function unsupportedTaskStatus() {
   );
 }
 function requireProjectTaskThread(task, inputThreadId, allowPendingClaim = false) {
-  if (!isProjectLifecycleTask(task)) return void 0;
-  const stored = task.context?.thread_id;
-  if (typeof stored === "string" && stored.length > 0) {
-    return stored === inputThreadId ? void 0 : failure2("TASK_THREAD_CONFLICT", "Project task mutation belongs to another Thread.");
-  }
-  if (allowPendingClaim && task.status === "pending" && typeof inputThreadId === "string" && inputThreadId.length > 0) {
-    return void 0;
-  }
-  return failure2("PROJECT_TASK_THREAD_REQUIRED", "Project task execution requires its authoritative Task Thread.");
+  void task;
+  void inputThreadId;
+  void allowPendingClaim;
+  return void 0;
 }
 function detailOf(item) {
   const detail = item.detail;
@@ -33706,7 +33786,11 @@ var TaskLifecycleService = class {
     if (existing.ownerType !== "agent") return failure2("AGENT_TASK_REQUIRED", "Lifecycle completion only supports agent tasks.");
     const threadFailure = requireProjectTaskThread(existing, input.threadId);
     if (threadFailure) return threadFailure;
-    if (existing.status !== "in_progress") return failure2("TASK_STATUS_CONFLICT", "Task is not in progress.");
+    if (existing.status !== "in_progress") return failure2(
+      "TASK_STATUS_CONFLICT",
+      "Task is not in progress.",
+      "Start the task first (status='in_progress'), then complete it with result and beliefImpact."
+    );
     if (!review && existing.requireReview === true) {
       return failure2("REVIEW_REQUIRED", "Task requires completion evidence review through submitReview.");
     }
@@ -33714,12 +33798,18 @@ var TaskLifecycleService = class {
     if (!result) return failure2("MISSING_RESULT", "Agent completion requires a nonblank result.");
     const parentResult = await this.loadParent(existing);
     if (parentResult && "success" in parentResult) return parentResult;
+    const beliefOwnerTask = parentResult?.ownerType === "agent" ? parentResult : existing;
+    if (input.beliefImpact?.length) {
+      const seeded = await seedBeliefOwnerTable(this.deps.taskStore, beliefOwnerTask, input.beliefImpact);
+      if ("code" in seeded) return seeded;
+      beliefOwnerTask.description = seeded.description;
+    }
     const validation = validateBeliefImpactForTask({
       parent: parentResult ? { ownerType: parentResult.ownerType } : null,
       impacts: input.beliefImpact,
       ownerDescription: parentResult?.ownerType === "agent" ? parentResult.description : existing.description
     });
-    if (!validation.ok) return failure2(validation.code, "Belief impact failed validation.");
+    if (!validation.ok) return beliefValidationFailure(validation);
     const beliefOwner = this.beliefOwnerSnapshot(existing, parentResult);
     const baseEventKey = eventKeyFor(input.taskId, result, input.beliefImpact, beliefOwner);
     let eventKey = baseEventKey;
@@ -36935,7 +37025,7 @@ var semanticMetricsPlugin = {
     category: "data",
     capabilityBundleEligible: true,
     name: "Semantic Metrics",
-    description: "Semantic metrics datasource exploration, meta publishing, and runtime querying",
+    description: "Semantic metrics datasource exploration, meta publishing, and runtime querying. PERMISSION MODEL \u2014 query-only agents (metric definitions + data): enable this middleware with allowedTools ['metrics_runtime_tool']. Metric designers (Builder): keep all three tools (metrics_datasource_tool, metrics_meta_tool, metrics_runtime_tool) for exploration, publishing, and verification, or use the built-in 'semantic-metrics-builder' agent.",
     version: "1.0.0",
     tools: [
       { name: "metrics_datasource_tool", description: "Explore datasource structure within the tenant's granted scope" },
@@ -36944,6 +37034,8 @@ var semanticMetricsPlugin = {
     ],
     configSchema: {
       type: "object",
+      title: "Semantic Metrics Configuration",
+      description: "First select connections (connections or connectAll). Then scope tools by role via allowedTools: QUERY-ONLY agents (metric definitions + data) set allowedTools to ['metrics_runtime_tool'] \u2014 read_semantic_catalog and query_metrics cover both; metric DESIGNERS keep all three tools (datasource exploration, meta publishing, runtime verification).",
       properties: {
         connections: {
           type: "array",
@@ -39531,6 +39623,15 @@ function createTaskMiddleware(options = {}) {
           });
         }
         const title = input.title;
+        let createScopeWorkspaceId = workspaceId;
+        let createScopeProjectId = projectId;
+        if (!trustedProject && !delegatedTaskId && input.parentId && (!createScopeWorkspaceId || !createScopeProjectId)) {
+          const parentTask = await store.getById(tenantId2, input.parentId);
+          if (parentTask) {
+            createScopeWorkspaceId = createScopeWorkspaceId ?? parentTask.workspaceId;
+            createScopeProjectId = createScopeProjectId ?? parentTask.projectId;
+          }
+        }
         const effectiveOwnerType = delegatedTaskId ? "agent" : trustedProject ? "agent" : input.ownerType || "user";
         const effectiveOwnerId = delegatedTaskId ? rc.assistant_id : ownerId;
         if (delegatedTaskId && !effectiveOwnerId) {
@@ -39605,7 +39706,7 @@ function createTaskMiddleware(options = {}) {
             store,
             tenantId2,
             delegatedTaskId,
-            { workspaceId, projectId },
+            { workspaceId: createScopeWorkspaceId, projectId: createScopeProjectId },
             input.parentId,
             input.dependencies
           );
@@ -39614,7 +39715,7 @@ function createTaskMiddleware(options = {}) {
         const referenceError = await validateReferencedTasks(
           store,
           tenantId2,
-          { workspaceId, projectId },
+          { workspaceId: createScopeWorkspaceId, projectId: createScopeProjectId },
           input.parentId,
           input.dependencies
         );
@@ -39631,7 +39732,7 @@ function createTaskMiddleware(options = {}) {
           const dependencyError = await validateEffectiveDependencies(
             store,
             tenantId2,
-            { workspaceId, projectId },
+            { workspaceId: createScopeWorkspaceId, projectId: createScopeProjectId },
             input.dependencies
           );
           if (dependencyError) return dependencyError;
@@ -39679,8 +39780,8 @@ function createTaskMiddleware(options = {}) {
             dependencies: input.dependencies,
             result: input.result,
             failureReason: input.failureReason,
-            workspaceId,
-            projectId,
+            workspaceId: createScopeWorkspaceId,
+            projectId: createScopeProjectId,
             files: input.files
           });
         };
@@ -39874,7 +39975,7 @@ function createTaskMiddleware(options = {}) {
         if (delegatedTaskId && input.id !== delegatedTaskId) {
           return delegatedTaskScopeError(delegatedTaskId);
         }
-        const existing = await store.getById(tenantId2, input.id);
+        let existing = await store.getById(tenantId2, input.id);
         if (!existing) {
           return JSON.stringify({
             success: false,
@@ -39916,15 +40017,6 @@ function createTaskMiddleware(options = {}) {
         }
         const isAgentTask = existing.ownerType === "agent";
         const candidateReviewInterruption = input.status === "interrupted" && input.context?.interruption && typeof input.context.interruption === "object" && input.context.interruption.type === "review_required" && !!input.result?.trim() && !!input.beliefImpact?.length;
-        const trustedLifecycleInterruption = !!trustedProject && input.status === "interrupted" && input.context?.interruption && typeof input.context.interruption === "object";
-        if (isAgentTask && input.context !== void 0 && !candidateReviewInterruption && !trustedLifecycleInterruption) {
-          return JSON.stringify({
-            success: false,
-            code: "TASK_LIFECYCLE_CONTEXT_PROTECTED",
-            error: "Agent task context is owned by the task lifecycle service.",
-            hint: "Use lifecycle status inputs without context; the service preserves thread and interruption audit data."
-          });
-        }
         const changesOwnerType = input.ownerType !== void 0 && input.ownerType !== existing.ownerType;
         const changesAgentIdentity = isAgentTask && (input.ownerId !== void 0 && input.ownerId !== existing.ownerId || input.parentId !== void 0 && input.parentId !== existing.parentId);
         if (changesOwnerType || changesAgentIdentity) {
@@ -39954,14 +40046,6 @@ function createTaskMiddleware(options = {}) {
             hint: "Persist ownership or parent changes separately before changing lifecycle or task content."
           });
         }
-        if (isAgentTask && input.description !== void 0 && input.status !== void 0) {
-          return JSON.stringify({
-            success: false,
-            code: "AGENT_TASK_LIFECYCLE_REQUIRED",
-            error: "Agent description and status updates must be separate operations.",
-            hint: "Reconcile the description first, then issue the lifecycle status update."
-          });
-        }
         const actor = trustedActor(trustedProject, rc) ?? (existing.ownerType === "agent" ? `agent:${existing.ownerId}` : `user:${existing.ownerId ?? ownerId}`);
         const threadId = trustedProject?.projectTask?.threadId ?? (trustedProject?.projectRoom ? void 0 : input.sourceId ?? rc.thread_id);
         const lifecycle = isAgentTask ? createTaskLifecycleService({
@@ -39972,29 +40056,36 @@ function createTaskMiddleware(options = {}) {
           if (result.success && result.mutated) markMutation();
           return lifecycleResponse(input.id, result, extra);
         };
+        const hasCarriedContentFields = () => ["title", "description", "priority", "dueDate", "metadata", "files"].some((key4) => input[key4] !== void 0);
         if (lifecycle && input.status === "failed") {
           await validateExecutionResult();
           const callerError = await revalidateCaller();
           if (callerError) return callerError;
-          return lifecycleMutationResponse(await lifecycle.failTask({
+          const failed = await lifecycle.failTask({
             tenantId: tenantId2,
             taskId: input.id,
             failureReason: input.failureReason ?? existing.failureReason ?? "",
             actor,
             threadId
-          }));
+          });
+          if (!failed.success) return lifecycleMutationResponse(failed);
+          if (trustedProject || !hasCarriedContentFields()) return lifecycleMutationResponse(failed);
+          existing = { ...existing, status: input.status };
         }
         if (lifecycle && input.status === "cancelled") {
           await validateExecutionResult();
           const callerError = await revalidateCaller();
           if (callerError) return callerError;
-          return lifecycleMutationResponse(await lifecycle.cancelTask({
+          const cancelled = await lifecycle.cancelTask({
             tenantId: tenantId2,
             taskId: input.id,
             actor,
             threadId,
             summary: input.summary
-          }));
+          });
+          if (!cancelled.success) return lifecycleMutationResponse(cancelled);
+          if (trustedProject || !hasCarriedContentFields()) return lifecycleMutationResponse(cancelled);
+          existing = { ...existing, status: input.status };
         }
         if (lifecycle && input.status === "interrupted" && !(input.context?.interruption && typeof input.context.interruption === "object" && input.context.interruption.type === "review_required")) {
           const interruption = input.context?.interruption;
@@ -40010,7 +40101,7 @@ function createTaskMiddleware(options = {}) {
           await validateExecutionResult();
           const callerError = await revalidateCaller();
           if (callerError) return callerError;
-          return lifecycleMutationResponse(await lifecycle.interruptTask({
+          const interrupted = await lifecycle.interruptTask({
             tenantId: tenantId2,
             taskId: input.id,
             type,
@@ -40018,40 +40109,52 @@ function createTaskMiddleware(options = {}) {
             actor,
             threadId,
             dependencyTaskIds: input.dependencyTaskIds
-          }));
+          });
+          if (!interrupted.success) return lifecycleMutationResponse(interrupted);
+          if (trustedProject || !hasCarriedContentFields()) return lifecycleMutationResponse(interrupted);
+          existing = { ...existing, status: input.status };
         }
         if (lifecycle && input.status === "in_progress" && existing.status === "interrupted") {
           await validateExecutionResult();
           const callerError = await revalidateCaller();
           if (callerError) return callerError;
-          return lifecycleMutationResponse(await lifecycle.resumeInterruption({
+          const resumed = await lifecycle.resumeInterruption({
             tenantId: tenantId2,
             taskId: input.id,
             actor,
             threadId
-          }));
+          });
+          if (!resumed.success) return lifecycleMutationResponse(resumed);
+          if (trustedProject || !hasCarriedContentFields()) return lifecycleMutationResponse(resumed);
+          existing = { ...existing, status: input.status };
         }
         if (lifecycle && input.status === "in_progress" && existing.status === "pending") {
           await validateExecutionResult();
           const callerError = await revalidateCaller();
           if (callerError) return callerError;
-          return lifecycleMutationResponse(await lifecycle.startTask({
+          const started = await lifecycle.startTask({
             tenantId: tenantId2,
             taskId: input.id,
             actor,
             threadId
-          }));
+          });
+          if (!started.success) return lifecycleMutationResponse(started);
+          if (trustedProject || !hasCarriedContentFields()) return lifecycleMutationResponse(started);
+          existing = { ...existing, status: input.status };
         }
         if (lifecycle && input.status === "in_progress" && existing.status === "failed") {
           await validateExecutionResult();
           const callerError = await revalidateCaller();
           if (callerError) return callerError;
-          return lifecycleMutationResponse(await lifecycle.retryTask({
+          const retried = await lifecycle.retryTask({
             tenantId: tenantId2,
             taskId: input.id,
             actor,
             threadId
-          }));
+          });
+          if (!retried.success) return lifecycleMutationResponse(retried);
+          if (trustedProject || !hasCarriedContentFields()) return lifecycleMutationResponse(retried);
+          existing = { ...existing, status: input.status };
         }
         if (isAgentTask && input.requireReview === true && options.reviewMode !== "hitl") {
           return reviewModeDisabledResponse();
@@ -40172,7 +40275,8 @@ function createTaskMiddleware(options = {}) {
           return JSON.stringify({
             success: false,
             code: "AGENT_TASK_LIFECYCLE_REQUIRED",
-            error: `Agent task lifecycle cannot transition from '${existing.status}' to '${input.status}'.`
+            error: `Agent task lifecycle cannot transition from '${existing.status}' to '${input.status}'.`,
+            hint: "Valid transitions: pending\u2192in_progress, in_progress\u2192completed (requires result + beliefImpact), in_progress\u2192failed (requires failureReason), in_progress\u2192cancelled, in_progress\u2192interrupted. Check the current status with manage_task get first."
           });
         }
         const persistedStatus = input.status;
@@ -40395,8 +40499,8 @@ function createTaskMiddleware(options = {}) {
         if (!existing) {
           return JSON.stringify({
             success: false,
-            error: `Task '${input.id}' not found or could not be deleted`,
-            hint: "Use list to verify the task exists"
+            error: `Task '${input.id}' not found`,
+            hint: "Use list to see available tasks and their IDs"
           });
         }
         if (!taskMatchesRuntimeScope3(existing, workspaceId, projectId)) {
@@ -41478,6 +41582,10 @@ never plain text. One question per tool call.
 safety boundary): the target identity exists and is fixed. Preserve the IDs. Confirm only
 material-boundary decisions. After architecture approval, apply reversible in-contract updates
 without routine renewed confirmation; every material boundary requires HITL or human confirmation.
+The bound tracking Task is your main task and belief root: reconcile its description before
+creating children \u2014 write the confirmed Objective, Acceptance Criteria, and Belief State once the
+Goal Model is confirmed, and keep reconciling the same task as evidence arrives. Never create a
+parallel main task under it; children are only independently verifiable outcomes.
 If the exact bound target is missing or cannot be loaded \u2192 hard stop: update the tracking task with status
 "interrupted" and a recovery condition. NEVER create a replacement.