@kynetic-ai/spec 0.10.0 → 0.12.0

package/dist/daemon/routes/agent-dispatch.ts

@@ -19,12 +19,15 @@
  * - @agent-dispatch-engine ac-4: CLI posts state change event to daemon
  */
 
+import path from 'node:path';
 import { Elysia, t } from 'elysia';
 import { DispatchEngine } from '../../agent-runtime/dispatch.js';
 import type { TaskStateChange, TaskStatus, InvocationEvent } from '../../agent-runtime/dispatch.js';
 import { DEFAULT_KSPEC_CLI_PATH } from '../../agent-runtime/invocation.js';
-import { initContext, loadMetaContext } from '../../parser/index.js';
+import { initContext, loadMetaContext, loadAllTasks, loadAllItems, ReferenceIndex, resolveProjectRoots } from '../../parser/index.js';
+import { getCompletedSessionCountsByAgent } from '../../sessions/store.js';
 import type { PubSubManager } from '../websocket/pubsub.js';
+import type { SessionEventData } from '@kynetic-ai/shared';
 
 const VALID_TASK_STATUSES = new Set<string>([
   "pending", "in_progress", "pending_review", "needs_work", "blocked", "completed", "cancelled",
@@ -43,31 +46,33 @@ export interface AgentDispatchRouteOptions {
  * Create a new dispatch engine with optional WebSocket broadcast wiring.
  * AC: @daemon-agent-dispatch ac-3, ac-4
  */
-function createEngine(projectDir: string, pubsub?: PubSubManager): DispatchEngine {
+function createEngine(
+  projectDir: string,
+  cwd?: string,
+  pubsub?: PubSubManager,
+): DispatchEngine {
   return new DispatchEngine({
     projectDir,
+    cwd,
     kspecCliPath: DEFAULT_KSPEC_CLI_PATH,
     onInvocationEvent: pubsub
       ? (event: InvocationEvent) => {
+          // AC: @ui-api-aggregation ac-4 - Include task_title for display
           pubsub.broadcast('agents', 'agent_invocation', {
             session_id: event.session_id,
             agent_id: event.agent_id,
             task_id: event.task_id ?? null,
+            task_title: event.task_title ?? null,
             status: event.status,
             timestamp: event.timestamp,
           }, projectDir);
         }
       : undefined,
+    // AC: @session-event-broadcast ac-replaces-text-chunks
     // AC: @cli-agent-commands ac-13, @daemon-agent-dispatch ac-8
-    onTextChunk: pubsub
-      ? (sessionId: string, agentId: string, taskId: string | null, text: string) => {
-          pubsub.broadcast('agents', 'agent_text_chunk', {
-            session_id: sessionId,
-            agent_id: agentId,
-            task_id: taskId,
-            text,
-            timestamp: Date.now(),
-          }, projectDir);
+    onSessionEvent: pubsub
+      ? (event: SessionEventData) => {
+          pubsub.broadcast('agents', event.type, event, projectDir);
         }
       : undefined,
   });
@@ -116,6 +121,28 @@ function processStateChangeEvent(
   return { accepted: true };
 }
 
+export function resolveDispatchCwd(
+  projectDir: string,
+  requestedCwd: string | null,
+): string {
+  if (requestedCwd && !path.isAbsolute(requestedCwd)) {
+    throw new Error('Dispatch cwd must be an absolute path');
+  }
+  const cwd = requestedCwd ? path.resolve(requestedCwd) : projectDir;
+
+  if (cwd === projectDir) {
+    return cwd;
+  }
+
+  const projectRoots = resolveProjectRoots(projectDir);
+  const cwdRoots = resolveProjectRoots(cwd);
+  if (!projectRoots || !cwdRoots || projectRoots.mainRoot !== cwdRoots.mainRoot) {
+    throw new Error('Dispatch cwd must belong to the same git project');
+  }
+
+  return cwd;
+}
+
 export function createAgentDispatchRoutes(options: AgentDispatchRouteOptions = {}) {
   const { pubsub } = options;
 
@@ -133,16 +160,34 @@ export function createAgentDispatchRoutes(options: AgentDispatchRouteOptions = {
     }, { body: stateChangeBodySchema })
 
     // AC: @daemon-agent-dispatch ac-6 - Unified dispatch start/stop via action field
-    .post('/dispatch', async ({ body, projectContext }) => {
+    .post('/dispatch', async ({ body, projectContext, request, set }) => {
       const projectDir = projectContext.path;
 
       if (body.action === 'start') {
+        let requestedCwd: string;
+        try {
+          requestedCwd = resolveDispatchCwd(projectDir, request.headers.get('X-Kspec-Cwd'));
+        } catch (err) {
+          set.status = 400;
+          return {
+            dispatch_enabled: false,
+            error: err instanceof Error ? err.message : String(err),
+          };
+        }
+
         let engine = engines.get(projectDir);
         if (engine?.getStatus().running) {
+          if (engine.getCwd() !== requestedCwd) {
+            set.status = 409;
+            return {
+              dispatch_enabled: true,
+              error: `Dispatch engine already running for ${projectDir} with cwd ${engine.getCwd()}`,
+            };
+          }
           return { dispatch_enabled: true, reason: 'Already running' };
         }
 
-        engine = createEngine(projectDir, pubsub);
+        engine = createEngine(projectDir, requestedCwd, pubsub);
         engines.set(projectDir, engine);
         await engine.start();
 
@@ -165,16 +210,34 @@ export function createAgentDispatchRoutes(options: AgentDispatchRouteOptions = {
     })
 
     // Start dispatch engine (legacy route)
-    .post('/dispatch/start', async ({ projectContext }) => {
+    .post('/dispatch/start', async ({ projectContext, request, set }) => {
       const projectDir = projectContext.path;
+      let requestedCwd: string;
+      try {
+        requestedCwd = resolveDispatchCwd(projectDir, request.headers.get('X-Kspec-Cwd'));
+      } catch (err) {
+        set.status = 400;
+        return {
+          started: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
 
       let engine = engines.get(projectDir);
       if (engine?.getStatus().running) {
+        if (engine.getCwd() !== requestedCwd) {
+          set.status = 409;
+          return {
+            started: false,
+            error: `Dispatch engine already running for ${projectDir} with cwd ${engine.getCwd()}`,
+            status: engine.getStatus(),
+          };
+        }
         return { started: false, reason: 'Already running', status: engine.getStatus() };
       }
 
       // AC: @agent-dispatch-engine ac-10 - pass kspecCliPath so task notes work from daemon-started engine
-      engine = createEngine(projectDir, pubsub);
+      engine = createEngine(projectDir, requestedCwd, pubsub);
       engines.set(projectDir, engine);
 
       await engine.start();
@@ -214,18 +277,29 @@ export function createAgentDispatchRoutes(options: AgentDispatchRouteOptions = {
     })
 
     // AC: @daemon-agent-dispatch ac-5 - Public status endpoint
+    // AC: @ui-api-ref-resolution ac-1 - Include task_title for active invocations
     .get('/status', async ({ projectContext }) => {
       const projectDir = projectContext.path;
       const engineStatus = engines.get(projectDir)?.getStatus();
 
-      let agentDefinitions: Array<{ id: string; name: string; adapter: string }> = [];
+      let agentDefinitions: Array<{ id: string; name: string; adapter: string; completed_sessions: number }> = [];
+      let completedCounts: Record<string, number> = {};
+      let refIndex: ReferenceIndex | null = null;
       try {
         const ctx = await initContext(projectDir);
-        const meta = await loadMetaContext(ctx);
+        const [meta, counts, tasks, items] = await Promise.all([
+          loadMetaContext(ctx),
+          getCompletedSessionCountsByAgent(ctx.specDir),
+          loadAllTasks(ctx),
+          loadAllItems(ctx),
+        ]);
+        completedCounts = counts;
+        refIndex = new ReferenceIndex(tasks, items);
         agentDefinitions = meta.agents.map((a) => ({
           id: a.id,
           name: a.name,
           adapter: a.adapter ?? 'claude-agent-acp',
+          completed_sessions: completedCounts[a.id] ?? 0,
         }));
       } catch {
         // Agent definitions unavailable — return empty array
@@ -233,12 +307,22 @@ export function createAgentDispatchRoutes(options: AgentDispatchRouteOptions = {
 
       return {
         dispatch_enabled: engineStatus?.running ?? false,
-        active_invocations: engineStatus?.invocations?.map((inv) => ({
-          session_id: inv.sessionId,
-          agent_id: inv.agentId,
-          task_ref: inv.taskRef ?? null,
-          elapsed_ms: inv.elapsedMs,
-        })) ?? [],
+        active_invocations: engineStatus?.invocations?.map((inv) => {
+          let task_title: string | null = null;
+          if (inv.taskRef && refIndex) {
+            const result = refIndex.resolve(inv.taskRef);
+            if (result.ok) {
+              task_title = (result.item as { title?: string }).title ?? null;
+            }
+          }
+          return {
+            session_id: inv.sessionId,
+            agent_id: inv.agentId,
+            task_ref: inv.taskRef ?? null,
+            task_title,
+            elapsed_ms: inv.elapsedMs,
+          };
+        }) ?? [],
         queue_depth: engineStatus?.queuedInvocations ?? 0,
         agent_definitions: agentDefinitions,
       };

package/dist/daemon/routes/aggregation.ts

@@ -0,0 +1,184 @@
+/**
+ * Aggregation API Routes
+ *
+ * Pre-computed server-side aggregation endpoints:
+ * - GET /api/aggregation/tasks/summary - Task status counts with dependency-aware distinctions
+ * - GET /api/aggregation/validation - Extended validation/alignment stats with entity and AC counts
+ * - GET /api/aggregation/inbox - Inbox items with inline triage status
+ *
+ * AC Coverage:
+ * - @ui-api-aggregation ac-1: Task status summary with ready vs blocked distinctions
+ * - @ui-api-aggregation ac-2: Validation/alignment stats with entity counts, AC counts, orphan counts
+ * - @ui-api-aggregation ac-3: Inbox items with inline triage status
+ */
+
+import { Elysia } from 'elysia';
+import {
+  initContext,
+  loadAllTasks,
+  loadInboxItems,
+  loadTriageRecords,
+  findTriageRecordByInboxRef,
+  buildIndexes,
+  validate,
+  AlignmentIndex,
+  areDependenciesMet,
+} from '../../parser/index.js';
+import type {
+  TaskStatusSummary,
+  ValidationAggregation,
+  InboxItemWithTriage,
+} from '@kynetic-ai/shared';
+
+interface AggregationRouteOptions {}
+
+export function createAggregationRoutes(options: AggregationRouteOptions = {}) {
+  return new Elysia({ prefix: '/api/aggregation' })
+    // AC: @ui-api-aggregation ac-1 - Task status summary with dependency-aware distinctions
+    .get('/tasks/summary', async ({ projectContext }) => {
+      const ctx = await initContext(projectContext.path);
+      const tasks = await loadAllTasks(ctx);
+
+      // Count tasks by status
+      const counts: Record<string, number> = {};
+      for (const task of tasks) {
+        counts[task.status] = (counts[task.status] || 0) + 1;
+      }
+
+      // Dependency-aware distinctions: ready vs blocked by incomplete dependencies
+      let ready = 0;
+      let blockedByDependencies = 0;
+      for (const task of tasks) {
+        if (task.status !== 'pending' && task.status !== 'needs_work') continue;
+        if (task.blocked_by.length > 0) {
+          blockedByDependencies++;
+        } else if (!areDependenciesMet(task, tasks)) {
+          blockedByDependencies++;
+        } else {
+          ready++;
+        }
+      }
+
+      const result: TaskStatusSummary = {
+        counts,
+        ready,
+        blocked_by_dependencies: blockedByDependencies,
+        total: tasks.length,
+      };
+
+      return result;
+    })
+
+    // AC: @ui-api-aggregation ac-2 - Extended validation/alignment stats
+    .get('/validation', async ({ projectContext }) => {
+      const ctx = await initContext(projectContext.path);
+      const { tasks, items, refIndex } = await buildIndexes(ctx);
+
+      // Run validation for error/warning counts and completeness data
+      const validationResult = await validate(ctx);
+
+      // Build alignment index
+      const alignIndex = new AlignmentIndex(tasks, items);
+      alignIndex.buildLinks(refIndex);
+      const alignStats = alignIndex.getStats();
+      const alignWarnings = alignIndex.findAlignmentWarnings();
+
+      // Entity counts
+      const traitCount = items.filter((item) => item.type === 'trait').length;
+
+      // AC counts from completeness warnings
+      // Count total ACs across all non-trait items
+      let totalACs = 0;
+      for (const item of items) {
+        if (item.type !== 'trait') {
+          totalACs += item.acceptance_criteria?.length || 0;
+        }
+      }
+
+      // Count uncovered ACs from completeness warnings
+      // Each warning represents one item with N uncovered ACs listed in details
+      // Details format: "Uncovered: ac-1, ac-2, ac-3"
+      const uncoveredWarnings = validationResult.completenessWarnings.filter(
+        (w) => w.type === 'missing_test_coverage' && w.subtype === 'own_ac'
+      );
+      let uncoveredCount = 0;
+      for (const warning of uncoveredWarnings) {
+        if (warning.details) {
+          // Parse "Uncovered: ac-1, ac-2, ac-3" to count individual ACs
+          const acList = warning.details.replace(/^Uncovered:\s*/, '');
+          uncoveredCount += acList.split(',').filter((s) => s.trim().length > 0).length;
+        }
+      }
+      const coveredCount = Math.max(0, totalACs - uncoveredCount);
+
+      const result: ValidationAggregation = {
+        stats: {
+          totalSpecs: alignStats.totalSpecs,
+          specsWithTasks: alignStats.specsWithTasks,
+          alignedSpecs: alignStats.alignedSpecs,
+          orphanedSpecs: alignStats.orphanedSpecs,
+        },
+        warnings: alignWarnings,
+        entity_counts: {
+          items: validationResult.stats.itemsChecked,
+          tasks: validationResult.stats.tasksChecked,
+          traits: traitCount,
+        },
+        ac_counts: {
+          total: totalACs,
+          covered: coveredCount,
+          uncovered: uncoveredCount,
+        },
+        orphan_count: validationResult.orphans.length,
+        valid: validationResult.valid,
+        error_count: validationResult.schemaErrors.length + validationResult.refErrors.length,
+        warning_count: validationResult.refWarnings.length + validationResult.completenessWarnings.length,
+      };
+
+      return result;
+    })
+
+    // AC: @ui-api-aggregation ac-3 - Inbox items with inline triage status
+    .get('/inbox', async ({ projectContext }) => {
+      const ctx = await initContext(projectContext.path);
+      const inboxItems = await loadInboxItems(ctx);
+      const triageRecords = await loadTriageRecords(ctx);
+
+      // Sort by created_at descending (newest first)
+      const sorted = [...inboxItems].sort(
+        (a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime()
+      );
+
+      // Merge triage status inline
+      const items: InboxItemWithTriage[] = sorted.map((item) => {
+        const triageRecord = findTriageRecordByInboxRef(triageRecords, item._ulid);
+
+        const result: InboxItemWithTriage = {
+          _ulid: item._ulid,
+          text: item.text,
+          tags: item.tags,
+          added_by: item.added_by,
+          created_at: item.created_at,
+        };
+
+        if (triageRecord) {
+          result.triage = {
+            _ulid: triageRecord._ulid,
+            status: triageRecord.status as 'pending' | 'triaged' | 'acted_on',
+            action: triageRecord.action as 'promote' | 'delete' | 'defer' | 'spec-gap' | 'duplicate' | undefined,
+            reasoning: triageRecord.reasoning,
+            decided_by: triageRecord.decided_by,
+            acted_at: triageRecord.acted_at,
+            result_ref: triageRecord.result_ref,
+          };
+        }
+
+        return result;
+      });
+
+      return {
+        items,
+        total: items.length,
+      };
+    });
+}

package/dist/daemon/routes/inbox.ts

@@ -88,9 +88,14 @@ export function createInboxRoutes(options: InboxRouteOptions) {
         await commitIfShadow(ctx.shadow, `inbox: add item ${item._ulid}`);
 
         // Broadcast update
+        // AC: @ui-api-aggregation ac-4 - Include full item data for in-place UI updates
         // AC: @multi-directory-daemon ac-18 - Broadcast scoped to request project
         pubsub.broadcast('inbox:updates', 'inbox_item_created', {
           ulid: item._ulid,
+          text: item.text,
+          tags: item.tags,
+          added_by: item.added_by,
+          created_at: item.created_at,
         }, projectContext.path);
 
         // AC: @api-contract ac-13 - Return item with generated ULID

package/dist/daemon/routes/items.ts

@@ -18,12 +18,17 @@ import {
   initContext,
   loadAllItems,
   loadAllTasks,
+  loadPlans,
+  findItemByRef,
+  findTaskByRef,
   ReferenceIndex,
   AlignmentIndex,
   getCachedTestCoverage,
   computeACCoverage,
   type LoadedSpecItem,
+  type LoadedTask,
 } from '../../parser/index.js';
+import { getRelatedSessionsForItem } from './session-related.js';
 
 interface ItemsRouteOptions {}
 
@@ -88,6 +93,49 @@ function computeParentMap(items: LoadedSpecItem[]): Map<string, string | undefin
   return parentMap;
 }
 
+function getItemImplementationStatus(item: LoadedSpecItem): string | undefined {
+  if (typeof item.status === 'string') {
+    return item.status;
+  }
+
+  return item.status?.implementation;
+}
+
+function getItemMaturity(item: LoadedSpecItem): string | undefined {
+  if (typeof item.status === 'object') {
+    return item.status?.maturity;
+  }
+
+  return undefined;
+}
+
+function toBatchSpecItemSummary(item: LoadedSpecItem) {
+  return {
+    kind: 'item',
+    ulid: item._ulid,
+    slugs: item.slugs,
+    title: item.title,
+    type: item.type,
+    status: getItemImplementationStatus(item),
+    maturity: getItemMaturity(item),
+    traits: item.traits ?? [],
+    ac_count: item.acceptance_criteria?.length ?? 0,
+  };
+}
+
+function toBatchTaskSummary(task: LoadedTask) {
+  return {
+    kind: 'task',
+    ulid: task._ulid,
+    slugs: task.slugs,
+    title: task.title,
+    status: task.status,
+    priority: task.priority,
+    spec_ref: task.spec_ref,
+    assignee: task.assignee,
+  };
+}
+
 export function createItemsRoutes(options: ItemsRouteOptions = {}) {
   // No closure-scoped kspecDir needed - comes from middleware
 
@@ -144,6 +192,26 @@ export function createItemsRoutes(options: ItemsRouteOptions = {}) {
           );
         }
 
+        // Plan filter — show only specs derived from a given plan
+        if (query.plan) {
+          const plans = await loadPlans(ctx);
+          const plan = plans.find(
+            (p) => p._ulid === query.plan || p.slugs.includes(query.plan!)
+          );
+          if (plan) {
+            const derivedRefs = new Set(
+              plan.derived_specs.map((r) => (r.startsWith('@') ? r.slice(1) : r))
+            );
+            filtered = filtered.filter(
+              (item) =>
+                derivedRefs.has(item._ulid) ||
+                item.slugs.some((s) => derivedRefs.has(s))
+            );
+          } else {
+            filtered = [];
+          }
+        }
+
         // Pagination
         const total = filtered.length;
         const offset = Number(query.offset) || 0;
@@ -178,12 +246,80 @@ export function createItemsRoutes(options: ItemsRouteOptions = {}) {
           maturity: t.Optional(t.Union([t.String(), t.Array(t.String())])),
           implementation: t.Optional(t.Union([t.String(), t.Array(t.String())])),
           tag: t.Optional(t.Union([t.String(), t.Array(t.String())])),
+          plan: t.Optional(t.String()),
           limit: t.Optional(t.String()),
           offset: t.Optional(t.String()),
         }),
       }
     )
 
+    .post(
+      '/batch',
+      async ({ body, error: errorResponse, projectContext }) => {
+        const refs = body.refs;
+
+        // AC: @trait-api-endpoint ac-3 - Validate body
+        if (!Array.isArray(refs)) {
+          return errorResponse(400, {
+            error: 'validation_error',
+            details: [
+              {
+                field: 'refs',
+                message: 'Refs is required and must be an array of item references',
+              },
+            ],
+          });
+        }
+
+        // AC: @batch-item-fetch-api ac-5 - Enforce max batch size
+        if (refs.length > 100) {
+          return errorResponse(400, {
+            error: 'validation_error',
+            details: [
+              {
+                field: 'refs',
+                message: 'Maximum batch size is 100 refs',
+              },
+            ],
+          });
+        }
+
+        // AC: @multi-directory-daemon ac-1, ac-24 - Use project context from middleware
+        const ctx = await initContext(projectContext.path);
+        const items = await loadAllItems(ctx);
+        const tasks = await loadAllTasks(ctx);
+
+        const resolvedItems = [];
+        const unresolved: string[] = [];
+
+        for (const ref of refs) {
+          const task = findTaskByRef(tasks, ref);
+          if (task) {
+            resolvedItems.push(toBatchTaskSummary(task));
+            continue;
+          }
+
+          const item = findItemByRef(items, ref);
+          if (item) {
+            resolvedItems.push(toBatchSpecItemSummary(item));
+            continue;
+          }
+
+          unresolved.push(ref);
+        }
+
+        return {
+          items: resolvedItems,
+          unresolved,
+        };
+      },
+      {
+        body: t.Object({
+          refs: t.Optional(t.Array(t.String())),
+        }),
+      }
+    )
+
     // AC: @api-contract ac-10 - Get single item by ref
     .get(
       '/:ref',
@@ -318,5 +454,36 @@ export function createItemsRoutes(options: ItemsRouteOptions = {}) {
           ref: t.String(),
         }),
       }
+    )
+
+    .get(
+      '/:ref/sessions',
+      async ({ params, error: errorResponse, projectContext }) => {
+        const ctx = await initContext(projectContext.path);
+        const items = await loadAllItems(ctx);
+        const tasks = await loadAllTasks(ctx);
+        const result = await getRelatedSessionsForItem({
+          itemRef: params.ref,
+          items,
+          tasks,
+          sessionsDir: ctx.sessionsDir,
+        });
+
+        if ('error' in result) {
+          return errorResponse(404, result.error);
+        }
+
+        return {
+          items: result.sessions,
+          total: result.sessions.length,
+          offset: 0,
+          limit: result.sessions.length,
+        };
+      },
+      {
+        params: t.Object({
+          ref: t.String(),
+        }),
+      }
     );
 }