nolo-cli 0.1.23 → 0.1.29

package/server/handlers/agentRun/taskRunToolHandler.ts

@@ -0,0 +1,579 @@
+import serverDb, { ensureServerDbOpen } from "../../../database/server/db";
+import { rowKey } from "../../../database/keys";
+import { handleToken } from "../../../auth/server/token";
+import { fetchMessages } from "../../../chat/messages/fetchMessages";
+import {
+  clearTaskRunBlocker,
+  closeTaskRunWorkItem,
+  planTaskRunDispatch,
+  prepareTaskRunMeta,
+  recordTaskRunAgentDispatch,
+  recordTaskRunAgentRun,
+  recordTaskRunArtifact,
+  recordTaskRunBlocker,
+  recordTaskRunDialog,
+  recordTaskRunReview,
+  requestTaskRunReview,
+  submitTaskRunOutcome,
+  upsertTaskRunWorkItems,
+  updateTaskRunWorkItem,
+  upsertTaskRunWorkItems,
+  type TaskRunBlocker,
+  type TaskRunDialog,
+  type TaskRunToolAction,
+  type TaskRunWorkItem,
+} from "../../../ai/taskRun/taskRunProtocol";
+
+export type TaskRunToolArgs = {
+  action?: TaskRunToolAction;
+  tenantId?: string;
+  tableId?: string;
+  rowId?: string;
+  dbKey?: string;
+  workItems?: TaskRunWorkItem[];
+  workItemId?: string;
+  agentKey?: string;
+  role?: string;
+  runId?: string;
+  runStatus?: "queued" | "running" | "completed" | "failed" | "timed_out";
+  dialogId?: string;
+  resultSummary?: string;
+  errorCode?: string;
+  toolsUsed?: string[];
+  toolTraceSummary?: {
+    callCount?: number;
+    resultCount?: number;
+    errorCount?: number;
+    rounds?: number;
+  };
+  artifact?: {
+    kind?: string;
+    ref?: string;
+    summary?: string;
+    producerRunId?: string;
+    workItemId?: string;
+  };
+  artifactIds?: string[];
+  blocker?: Omit<TaskRunBlocker, "id" | "createdAt">;
+  reviewerAgentKey?: string;
+  reviewStatus?: "passed" | "needs_changes" | "blocked";
+  targetWorkItemId?: string;
+  findings?: any[];
+  blockerId?: string;
+  participantAgentKeys?: string[];
+  purpose?: TaskRunDialog["purpose"];
+  message?: string;
+  summary?: string;
+  reason?: string;
+};
+
+const json = (value: unknown): string => JSON.stringify(value);
+const EVIDENCE_DIALOG_LIMIT = 8;
+const EVIDENCE_TEXT_LIMIT = 1200;
+const EVIDENCE_DIALOG_MAX_COUNT = 12;
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function pickString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function compactText(value: unknown, maxChars = EVIDENCE_TEXT_LIMIT): string | undefined {
+  const text = pickString(value);
+  if (!text) return undefined;
+  return text.length <= maxChars ? text : `${text.slice(0, maxChars)}...`;
+}
+
+function uniqueStrings(values: unknown[]): string[] {
+  const result: string[] = [];
+  for (const value of values) {
+    if (typeof value !== "string" || !value.trim()) continue;
+    const normalized = value.trim();
+    if (!result.includes(normalized)) result.push(normalized);
+  }
+  return result;
+}
+
+function textFromMessageContent(content: unknown): string | undefined {
+  if (typeof content === "string") return compactText(content);
+  if (!Array.isArray(content)) return undefined;
+  const text = content
+    .filter((part) => isRecord(part) && part.type === "text" && typeof part.text === "string")
+    .map((part) => part.text)
+    .join("")
+    .trim();
+  return compactText(text);
+}
+
+function collectDialogIdsFromRow(row: any, meta: any): string[] {
+  const candidates: unknown[] = [];
+  const activityRefs = Array.isArray(meta.activityRefs) ? meta.activityRefs : [];
+  for (const ref of activityRefs) {
+    if (isRecord(ref)) candidates.push(ref.dialogId);
+  }
+  if (isRecord(meta.latestActivityRef)) candidates.push(meta.latestActivityRef.dialogId);
+  for (const run of Array.isArray(meta.agentRuns) ? meta.agentRuns : []) {
+    if (isRecord(run)) candidates.push(run.dialogId);
+  }
+  for (const item of Array.isArray(meta.workItems) ? meta.workItems : []) {
+    if (!isRecord(item)) continue;
+    candidates.push(...(Array.isArray(item.dialogIds) ? item.dialogIds : []));
+    if (isRecord(item.outcome)) candidates.push(item.outcome.dialogId);
+  }
+  if (isRecord(meta.review)) candidates.push(meta.review.dialogId);
+  for (const event of Array.isArray(meta.taskEvents) ? meta.taskEvents : []) {
+    if (isRecord(event)) candidates.push(event.dialogId);
+  }
+  if (pickString(row?.parentDialogId)) candidates.push(row.parentDialogId);
+  return uniqueStrings(candidates).slice(-EVIDENCE_DIALOG_MAX_COUNT);
+}
+
+async function summarizeDialogEvidence(dialogId: string, userId: string) {
+  const dialogKey = `dialog-${userId}-${dialogId}`;
+  const dialog = await serverDb.get(dialogKey).catch(() => null);
+  if (!dialog || dialog.deletedAt) {
+    return {
+      dialogId,
+      dialogKey,
+      status: "unavailable",
+      error: "dialog not found in current task tenant",
+    };
+  }
+
+  const messages = await fetchMessages(serverDb, dialogId, {
+    limit: EVIDENCE_DIALOG_LIMIT,
+  });
+  const ordered = [...messages].reverse();
+  const toolMessages = ordered.filter((message: any) => message?.role === "tool" || message?.authorRole === "tool");
+  const assistantMessages = ordered.filter((message: any) => message?.role === "assistant" || message?.authorRole === "assistant");
+  const lastAssistant = assistantMessages.at(-1);
+  const checkpoint = isRecord(dialog.runtimeCheckpoint) ? dialog.runtimeCheckpoint : {};
+
+  return {
+    dialogId,
+    dialogKey,
+    status: pickString(dialog.status) ?? "unknown",
+    title: pickString(dialog.title),
+    agentKey: pickString(dialog.agentKey) ?? pickString(dialog.cybotKey),
+    parentDialogId: pickString(dialog.parentDialogId),
+    updatedAt: dialog.updatedAt,
+    messageCountSample: ordered.length,
+    toolMessageCountSample: toolMessages.length,
+    toolsUsed: Array.isArray(dialog.toolsUsed)
+      ? uniqueStrings(dialog.toolsUsed)
+      : uniqueStrings(toolMessages.map((message: any) => message?.toolName ?? message?.name)),
+    writtenFiles: Array.isArray(dialog.writtenFiles) ? uniqueStrings(dialog.writtenFiles) : [],
+    toolErrors: Array.isArray(dialog.toolErrors) ? uniqueStrings(dialog.toolErrors) : [],
+    artifacts: dialog.artifacts ?? null,
+    runtimeCheckpoint: {
+      status: checkpoint.status,
+      toolCallCount: checkpoint.toolCallCount,
+      traceSummary: checkpoint.traceSummary,
+      lastToolNames: checkpoint.lastToolNames,
+      workspaceProgress: checkpoint.workspaceProgress,
+    },
+    lastAssistantText: textFromMessageContent(lastAssistant?.content) ?? compactText(dialog.agentReply),
+  };
+}
+
+async function buildEvidenceBundle(args: {
+  row: any;
+  meta: any;
+  userId: string;
+}) {
+  const dialogIds = collectDialogIdsFromRow(args.row, args.meta);
+  const dialogSummaries = [];
+  for (const dialogId of dialogIds) {
+    dialogSummaries.push(await summarizeDialogEvidence(dialogId, args.userId));
+  }
+  return {
+    generatedAt: new Date().toISOString(),
+    scope: {
+      rowId: args.row.rowId,
+      rowDbKey: args.row.dbKey,
+      tableId: args.row.tableId,
+    },
+    dialogIds,
+    dialogSummaries,
+    artifacts: Array.isArray(args.meta.artifacts) ? args.meta.artifacts : [],
+    review: isRecord(args.meta.review) ? args.meta.review : undefined,
+    blockers: Array.isArray(args.meta.blockers) ? args.meta.blockers : [],
+    note:
+      "This bundle is generated from the current task row and linked dialogs only. Use it as bounded review evidence when direct dialog reads are unavailable.",
+  };
+}
+
+async function getUserIdFromToken(authToken: string): Promise<string> {
+  if (!authToken) throw new Error("Unauthorized: auth token is required");
+  const req: any = {
+    headers: {
+      get: (name: string) =>
+        name.toLowerCase() === "authorization" ? `Bearer ${authToken}` : null,
+    },
+  };
+  const user = await handleToken(req, {});
+  if (!user?.userId) throw new Error("Unauthorized: userId not found");
+  return user.userId;
+}
+
+function resolveTaskRowDbKey(args: TaskRunToolArgs): string {
+  if (typeof args.dbKey === "string" && args.dbKey.trim()) return args.dbKey.trim();
+  const tenantId = typeof args.tenantId === "string" ? args.tenantId.trim() : "";
+  const tableId = typeof args.tableId === "string" ? args.tableId.trim() : "";
+  const rowId = typeof args.rowId === "string" ? args.rowId.trim() : "";
+  if (!tenantId || !tableId || !rowId) {
+    throw new Error("taskRun requires dbKey or tenantId/tableId/rowId.");
+  }
+  return rowKey.single(tenantId, tableId, rowId);
+}
+
+function assertWorkItems(input: unknown, existingItems: TaskRunWorkItem[] = []): TaskRunWorkItem[] {
+  if (!Array.isArray(input) || input.length === 0) {
+    throw new Error("taskRun.updateWorkItems requires a non-empty workItems array.");
+  }
+  return input.map((item, index) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new Error(`workItems[${index}] must be an object.`);
+    }
+    const id = typeof (item as any).id === "string" ? (item as any).id.trim() : "";
+    if (!id) throw new Error(`workItems[${index}] requires id.`);
+    const existing = existingItems.find((workItem) => workItem.id === id);
+    const title =
+      typeof (item as any).title === "string" && (item as any).title.trim()
+        ? (item as any).title.trim()
+        : existing?.title;
+    if (!title) throw new Error(`workItems[${index}] requires title for new work items.`);
+    return {
+      ...(item as TaskRunWorkItem),
+      id,
+      title,
+      status: (item as any).status ?? existing?.status ?? "pending",
+    };
+  });
+}
+
+function assertString(value: unknown, name: string): string {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`taskRun.${name} is required.`);
+  return value.trim();
+}
+
+function optionalStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string" && Boolean(item.trim())).map((item) => item.trim());
+}
+
+function optionalToolTraceSummary(value: unknown) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const summary = value as Record<string, unknown>;
+  return {
+    callCount: typeof summary.callCount === "number" ? summary.callCount : 0,
+    resultCount: typeof summary.resultCount === "number" ? summary.resultCount : 0,
+    errorCount: typeof summary.errorCount === "number" ? summary.errorCount : 0,
+    rounds: typeof summary.rounds === "number" ? summary.rounds : 0,
+  };
+}
+
+function summarizeRow(row: any) {
+  return {
+    rowId: row.rowId,
+    title: row.title,
+    status: row.status,
+    owner: row.owner,
+    priority: row.priority,
+    meta: row.meta,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function isSelfWorkItemReference(row: any, workItemId: string): boolean {
+  return workItemId === "self" || workItemId === row?.rowId || workItemId === row?.dbKey;
+}
+
+function ensureSelfWorkItem(args: {
+  row: any;
+  meta: any;
+  workItemId: string;
+  status: TaskRunWorkItem["status"];
+  now: string;
+}) {
+  if ((args.meta.workItems ?? []).some((item: TaskRunWorkItem) => item.id === args.workItemId)) {
+    return args.meta;
+  }
+  if (!isSelfWorkItemReference(args.row, args.workItemId)) {
+    return args.meta;
+  }
+  return upsertTaskRunWorkItems({
+    meta: args.meta,
+    now: args.now,
+    workItems: [
+      {
+        id: args.workItemId,
+        kind: "work",
+        title: args.row.title ?? args.workItemId,
+        ownerAgent: typeof args.row.owner === "string" ? args.row.owner : undefined,
+        status: args.status,
+        reviewPolicy: "after_item",
+      },
+    ],
+  });
+}
+
+export async function runTaskRunToolForUser(args: TaskRunToolArgs, userId: string): Promise<string> {
+  try {
+    await ensureServerDbOpen();
+    const action = args.action;
+    if (!action) throw new Error("taskRun.action is required.");
+
+    const rowDbKey = resolveTaskRowDbKey(args);
+    const row = await serverDb.get(rowDbKey).catch(() => null);
+    if (!row || row.deletedAt) throw new Error(`Task row not found: ${rowDbKey}`);
+    if (row.tenantId !== userId) throw new Error("Forbidden: task row tenant mismatch");
+
+    const now = new Date().toISOString();
+    const prepared = prepareTaskRunMeta({ row, now });
+    let meta = prepared.meta;
+    let payload: Record<string, unknown> = {};
+
+    switch (action) {
+      case "readContext":
+      case "readTaskContext":
+      case "queryReadyWorkItems":
+        payload = {
+          plan: planTaskRunDispatch(meta),
+          evidenceBundle: await buildEvidenceBundle({ row, meta, userId }),
+        };
+        break;
+      case "updateWorkItems":
+      case "upsertWorkItem":
+        meta = upsertTaskRunWorkItems({
+          meta,
+          workItems: assertWorkItems(args.workItems, meta.workItems ?? []),
+          now,
+        });
+        payload = { plan: planTaskRunDispatch(meta) };
+        break;
+      case "claimOrDispatch": {
+        // Compatibility path. New agents should prefer claimWorkItem + openDialog so claiming and communication stay separate.
+      }
+      case "claimWorkItem": {
+        const workItemId = assertString(args.workItemId, "workItemId");
+        meta = ensureSelfWorkItem({ row, meta, workItemId, status: "ready", now });
+        const plan = planTaskRunDispatch(meta);
+        if (!plan.ready.some((item) => item.id === workItemId)) {
+          return json({
+            ok: false,
+            error: "TASK_WORK_ITEM_NOT_READY",
+            plan,
+          });
+        }
+        const dispatched = recordTaskRunAgentDispatch({
+          meta,
+          workItemId,
+          agentKey: assertString(args.agentKey, "agentKey"),
+          role: args.role,
+          now,
+        });
+        if (!dispatched.workItem || !dispatched.agentRun) {
+          throw new Error(`Task work item not found: ${workItemId}`);
+        }
+        meta = dispatched.meta;
+        payload = { workItem: dispatched.workItem, agentRun: dispatched.agentRun };
+        break;
+      }
+      case "recordAgentRun": {
+        const toolsUsed = optionalStringArray(args.toolsUsed);
+        const toolTraceSummary = optionalToolTraceSummary(args.toolTraceSummary);
+        const recorded = recordTaskRunAgentRun({
+          meta,
+          run: {
+            ...(args.runId ? { id: args.runId } : {}),
+            agentKey: assertString(args.agentKey, "agentKey"),
+            ...(args.role ? { role: args.role } : {}),
+            status: args.runStatus ?? "completed",
+            ...(args.workItemId ? { workItemId: args.workItemId } : {}),
+            ...(args.dialogId ? { dialogId: args.dialogId } : {}),
+            ...(args.resultSummary ? { resultSummary: args.resultSummary } : {}),
+            ...(args.errorCode ? { errorCode: args.errorCode } : {}),
+            ...(toolsUsed.length ? { toolsUsed } : {}),
+            ...(toolTraceSummary ? { toolTraceSummary } : {}),
+          },
+          now,
+        });
+        meta = recorded.meta;
+        payload = { agentRun: recorded.agentRun };
+        break;
+      }
+      case "openDialog": {
+        const participantAgentKeys = optionalStringArray(args.participantAgentKeys);
+        const fallbackParticipant = args.agentKey ?? args.reviewerAgentKey;
+        const recorded = recordTaskRunDialog({
+          meta,
+          purpose: args.purpose ?? "handoff",
+          participantAgentKeys: participantAgentKeys.length > 0 ? participantAgentKeys : fallbackParticipant ? [fallbackParticipant] : [],
+          workItemIds: args.workItemId ? [args.workItemId] : undefined,
+          message: args.message,
+          now,
+        });
+        if (recorded.dialog.participantAgentKeys.length === 0) {
+          throw new Error("taskRun.openDialog requires participantAgentKeys, agentKey, or reviewerAgentKey.");
+        }
+        meta = recorded.meta;
+        payload = {
+          dialog: recorded.dialog,
+          startedAgent: false,
+          nextAction:
+            "taskRun.openDialog only records a durable dialog link/assignment intent. To actually start the target agent, call startAgentDialog with the targetAgentKey and full message.",
+        };
+        break;
+      }
+      case "recordArtifact": {
+        const artifact = args.artifact;
+        if (!artifact || typeof artifact !== "object") throw new Error("taskRun.artifact is required.");
+        const recorded = recordTaskRunArtifact({
+          meta,
+          artifact: {
+            kind: assertString(artifact.kind, "artifact.kind"),
+            ref: assertString(artifact.ref, "artifact.ref"),
+            summary: assertString(artifact.summary, "artifact.summary"),
+            producerRunId: artifact.producerRunId,
+            workItemId: artifact.workItemId,
+          },
+          now,
+        });
+        meta = recorded.meta;
+        payload = { artifact: recorded.artifact };
+        break;
+      }
+      case "markBlocked":
+      case "setBlocker": {
+        const blocker = args.blocker;
+        if (!blocker || typeof blocker !== "object") throw new Error("taskRun.blocker is required.");
+        const recorded = recordTaskRunBlocker({
+          meta,
+          blocker: {
+            ...blocker,
+            layer: assertString(blocker.layer, "blocker.layer"),
+            code: assertString(blocker.code, "blocker.code"),
+            message: assertString(blocker.message, "blocker.message"),
+          },
+          now,
+        });
+        meta = recorded.meta;
+        if (args.workItemId) {
+          meta = ensureSelfWorkItem({ row, meta, workItemId: args.workItemId, status: "running", now });
+          meta = updateTaskRunWorkItem({
+            meta,
+            id: args.workItemId,
+            status: "blocked",
+            blockerIds: [recorded.blocker.id],
+            now,
+          }).meta;
+        }
+        payload = { blocker: recorded.blocker };
+        break;
+      }
+      case "clearBlocker": {
+        const cleared = clearTaskRunBlocker({
+          meta,
+          blockerId: assertString(args.blockerId, "blockerId"),
+          workItemId: args.workItemId,
+          now,
+        });
+        if (!cleared.blocker) throw new Error(`Task blocker not found: ${args.blockerId}`);
+        meta = cleared.meta;
+        payload = { blocker: cleared.blocker, workItem: cleared.workItem };
+        break;
+      }
+      case "requestReview": {
+        const reviewed = requestTaskRunReview({
+          meta,
+          reviewerAgentKey: assertString(args.reviewerAgentKey, "reviewerAgentKey"),
+          targetWorkItemId: args.workItemId,
+          artifactIds: args.artifactIds,
+          dialogId: args.dialogId,
+          message: args.message,
+          now,
+        });
+        meta = reviewed.meta;
+        payload = { review: reviewed.review };
+        break;
+      }
+      case "recordReview": {
+        const reviewed = recordTaskRunReview({
+          meta,
+          status: args.reviewStatus ?? "blocked",
+          targetWorkItemId: args.targetWorkItemId ?? args.workItemId,
+          reviewerAgentKey: args.reviewerAgentKey,
+          artifactIds: args.artifactIds,
+          dialogId: args.dialogId,
+          findings: args.findings,
+          now,
+        });
+        meta = reviewed.meta;
+        payload = { review: reviewed.review };
+        break;
+      }
+      case "submitOutcome": {
+        const workItemId = assertString(args.workItemId, "workItemId");
+        meta = ensureSelfWorkItem({ row, meta, workItemId, status: "running", now });
+        const submitted = submitTaskRunOutcome({
+          meta,
+          workItemId,
+          summary: assertString(args.summary ?? args.reason, "summary"),
+          dialogId: args.dialogId,
+          artifactIds: args.artifactIds,
+          now,
+        });
+        if (!submitted.workItem) throw new Error(`Task work item not found: ${args.workItemId}`);
+        meta = submitted.meta;
+        payload = { workItem: submitted.workItem, plan: planTaskRunDispatch(meta) };
+        break;
+      }
+      case "completeWorkItem":
+      case "closeWorkItem": {
+        const workItemId = assertString(args.workItemId, "workItemId");
+        meta = ensureSelfWorkItem({ row, meta, workItemId, status: "running", now });
+        const completed = closeTaskRunWorkItem({
+          meta,
+          workItemId,
+          summary: args.summary ?? "Completed",
+          reason: args.reason,
+          dialogId: args.dialogId,
+          artifactIds: args.artifactIds,
+          now,
+        });
+        if (!completed.workItem) throw new Error(`Task work item not found: ${args.workItemId}`);
+        meta = completed.meta;
+        const items = meta.workItems ?? [];
+        if (items.length > 0 && items.every((item) => item.status === "completed") && meta.taskRun) {
+          meta.taskRun = { ...meta.taskRun, phase: "completed", updatedAt: now };
+        }
+        payload = { workItem: completed.workItem, plan: planTaskRunDispatch(meta) };
+        break;
+      }
+      default:
+        throw new Error(`Unsupported taskRun action: ${String(action)}`);
+    }
+
+    const updated = { ...row, meta, updatedAt: now };
+    await serverDb.put(rowDbKey, updated);
+    return json({
+      ok: true,
+      action,
+      row: summarizeRow(updated),
+      ...payload,
+    });
+  } catch (error: any) {
+    return json({
+      ok: false,
+      error: error?.message ?? "taskRun failed",
+    });
+  }
+}
+
+export async function runTaskRunTool(args: TaskRunToolArgs, authToken: string): Promise<string> {
+  const userId = await getUserIdFromToken(authToken);
+  return runTaskRunToolForUser(args, userId);
+}