@kynetic-ai/spec 0.10.0 → 0.12.0

package/dist/daemon/routes/meta.ts

@@ -4,14 +4,20 @@
  * REST endpoints for meta operations:
  * - GET /api/meta/session - get session context
  * - GET /api/meta/agents - list agents
+ * - PATCH /api/meta/agents/:id - update agent definition
  * - GET /api/meta/workflows - list workflows
  * - GET /api/meta/observations - list observations with filter
+ * - GET /api/meta/config - project config from manifest + kspec.config.yaml
+ * - GET /api/meta/shadow - shadow branch status
+ * - GET /api/meta/conventions - convention definitions
  *
  * AC Coverage:
  * - ac-15: GET /api/meta/session returns session context
  * - ac-16: GET /api/meta/agents returns all agents
  * - ac-17: GET /api/meta/workflows returns all workflows
  * - ac-18: GET /api/meta/observations with filter
+ * - @ui-agent-dispatch ac-4: PATCH /api/meta/agents/:id updates agent definition
+ * - @ui-settings-view ac-1: GET /api/meta/config, /shadow, /conventions
  */
 
 import { Elysia, t } from 'elysia';
@@ -19,7 +25,11 @@ import {
   initContext,
   loadMetaContext,
   loadSessionContext,
+  saveMetaItem,
 } from '../../parser/index.js';
+import { commitIfShadow, getShadowStatus, hasRemoteTracking } from '../../parser/shadow.js';
+import type { Agent } from '../../schema/meta.js';
+import { AgentDispatchEventSchema } from '../../schema/meta.js';
 
 interface MetaRouteOptions {}
 
@@ -57,6 +67,73 @@ export function createMetaRoutes(options: MetaRouteOptions = {}) {
       };
     })
 
+    // AC: @ui-agent-dispatch ac-4 - Update agent definition
+    // Body schema mirrors editable fields from AgentSchema (src/schema/meta.ts).
+    // Dispatch event enum values derived from AgentDispatchEventSchema.
+    .patch(
+      '/agents/:id',
+      async ({ params, body, projectContext }) => {
+        const ctx = await initContext(projectContext.path);
+        const meta = await loadMetaContext(ctx);
+
+        // Find the agent by id
+        const agent = meta.agents.find((a) => a.id === params.id);
+        if (!agent) {
+          throw new Error(`Agent not found: ${params.id}`);
+        }
+
+        // Apply partial updates from body — result satisfies Agent type from schema
+        const updated: Agent = { ...agent, ...body };
+
+        await saveMetaItem(ctx, updated, 'agent');
+        await commitIfShadow(ctx.shadow, `meta: update agent ${params.id}`);
+
+        return updated;
+      },
+      {
+        params: t.Object({
+          id: t.String(),
+        }),
+        // Editable fields from AgentSchema — dispatch.on enum derived from AgentDispatchEventSchema
+        body: t.Object({
+          name: t.Optional(t.String()),
+          description: t.Optional(t.String()),
+          adapter: t.Optional(t.String()),
+          dispatch: t.Optional(
+            t.Array(
+              t.Object({
+                on: t.Union(AgentDispatchEventSchema.options.map((v) => t.Literal(v))),
+                filter: t.Optional(
+                  t.Object({
+                    automation: t.Optional(t.Union([t.Literal('eligible'), t.Literal('ineligible')])),
+                    tags: t.Optional(t.Array(t.String())),
+                    priority: t.Optional(t.Number()),
+                  })
+                ),
+              })
+            )
+          ),
+          capabilities: t.Optional(t.Array(t.String())),
+          tools: t.Optional(t.Array(t.String())),
+          skills: t.Optional(t.Array(t.String())),
+          budget: t.Optional(
+            t.Object({
+              max_tasks: t.Optional(t.Number()),
+              max_retries: t.Optional(t.Number()),
+              timeout_minutes: t.Optional(t.Number()),
+            })
+          ),
+          concurrency: t.Optional(
+            t.Object({
+              max_concurrent: t.Optional(t.Number()),
+            })
+          ),
+          auto_approve: t.Optional(t.Boolean()),
+          prompt_template: t.Optional(t.String()),
+        }),
+      }
+    )
+
     // AC: @api-contract ac-17 - List workflows
     .get('/workflows', async ({ projectContext }) => {
       // AC: @multi-directory-daemon ac-1, ac-24 - Use project context from middleware
@@ -114,5 +191,68 @@ export function createMetaRoutes(options: MetaRouteOptions = {}) {
           type: t.Optional(t.Union([t.String(), t.Array(t.String())])),
         }),
       }
-    );
+    )
+
+    // AC: @ui-settings-view ac-1 - Project config from manifest
+    .get('/config', async ({ projectContext }) => {
+      const ctx = await initContext(projectContext.path);
+      const manifest = ctx.manifest;
+      const config = ctx.config;
+
+      return {
+        project: manifest?.project ?? null,
+        spec_version: manifest?.kynetic ?? null,
+        root_dir: ctx.projectRoot,
+        remote_tracking: config.shadow.remote
+          ? { value: config.shadow.remote.value, type: config.shadow.remote.type }
+          : null,
+        daemon: {
+          port: config.daemon.port,
+          host: config.daemon.host,
+          auto_start: config.daemon.auto_start,
+        },
+      };
+    })
+
+    // AC: @ui-settings-view ac-1 - Shadow branch status
+    .get('/shadow', async ({ projectContext }) => {
+      const ctx = await initContext(projectContext.path);
+
+      if (!ctx.shadow) {
+        return {
+          enabled: false,
+          branch_name: null,
+          worktree_dir: null,
+          healthy: false,
+          remote_tracking: false,
+        };
+      }
+
+      const status = await getShadowStatus(ctx.rootDir, {
+        branchName: ctx.shadow.branchName,
+        directory: ctx.config.shadow.directory,
+      });
+      const hasRemote = await hasRemoteTracking(ctx.shadow.worktreeDir, {
+        branchName: ctx.shadow.branchName,
+      });
+
+      return {
+        enabled: ctx.shadow.enabled,
+        branch_name: ctx.shadow.branchName,
+        worktree_dir: ctx.shadow.worktreeDir,
+        healthy: status.healthy,
+        remote_tracking: hasRemote,
+      };
+    })
+
+    // AC: @ui-settings-view ac-1 - Convention definitions
+    .get('/conventions', async ({ projectContext }) => {
+      const ctx = await initContext(projectContext.path);
+      const meta = await loadMetaContext(ctx);
+
+      return {
+        items: meta.conventions,
+        total: meta.conventions.length,
+      };
+    });
 }

package/dist/daemon/routes/plans.ts

@@ -0,0 +1,147 @@
+/**
+ * Plans API Routes
+ *
+ * REST endpoints for plan operations:
+ * - GET /api/plans - list plans with status filter and task progress
+ * - GET /api/plans/:ref - get single plan with content
+ *
+ * AC Coverage:
+ * - @ui-plans-view ac-1: Plan list with title, status, dates, linked counts, progress
+ * - @ui-plans-view ac-2: Plan detail with content for expand/detail view
+ */
+
+import { Elysia, t } from 'elysia';
+import {
+  initContext,
+  loadPlans,
+  loadAllTasks,
+  findPlanByRef,
+  type LoadedPlan,
+} from '../../parser/index.js';
+import type { PlanSummary, PlanDetail } from '@kynetic-ai/shared';
+
+interface PlansRouteOptions {}
+
+/**
+ * Build a task status lookup map from loaded tasks.
+ */
+function buildTaskStatusMap(tasks: Array<{ _ulid: string; slugs: string[]; status: string }>) {
+  const tasksByRef = new Map<string, { status: string }>();
+  for (const task of tasks) {
+    tasksByRef.set(task._ulid, { status: task.status });
+    for (const slug of task.slugs) {
+      tasksByRef.set(slug, { status: task.status });
+    }
+  }
+  return tasksByRef;
+}
+
+/**
+ * Compute task progress for a plan's derived tasks.
+ */
+function computeTaskProgress(
+  derivedTasks: string[],
+  tasksByRef: Map<string, { status: string }>
+) {
+  const progress = { total: 0, completed: 0, in_progress: 0, pending: 0, blocked: 0 };
+  for (const ref of derivedTasks) {
+    const cleanRef = ref.startsWith('@') ? ref.slice(1) : ref;
+    const task = tasksByRef.get(cleanRef);
+    if (task) {
+      progress.total++;
+      if (task.status === 'completed') progress.completed++;
+      else if (task.status === 'in_progress' || task.status === 'pending_review' || task.status === 'needs_work') progress.in_progress++;
+      else if (task.status === 'blocked') progress.blocked++;
+      else progress.pending++;
+    }
+  }
+  return progress;
+}
+
+/**
+ * Map a loaded plan to a PlanSummary.
+ */
+function toPlanSummary(
+  plan: LoadedPlan,
+  tasksByRef: Map<string, { status: string }>
+): PlanSummary {
+  return {
+    _ulid: plan._ulid,
+    slugs: plan.slugs,
+    title: plan.title,
+    status: plan.status,
+    created_at: plan.created_at,
+    approved_at: plan.approved_at ?? undefined,
+    completed_at: plan.completed_at ?? undefined,
+    derived_specs: plan.derived_specs,
+    derived_tasks: plan.derived_tasks,
+    spec_count: plan.derived_specs.length,
+    task_count: plan.derived_tasks.length,
+    task_progress: computeTaskProgress(plan.derived_tasks, tasksByRef),
+  };
+}
+
+export function createPlansRoutes(options: PlansRouteOptions = {}) {
+  return new Elysia({ prefix: '/api/plans' })
+    // AC: @ui-plans-view ac-1 - List plans with progress
+    .get(
+      '/',
+      async ({ query, projectContext }) => {
+        const ctx = await initContext(projectContext.path);
+        const plans = await loadPlans(ctx);
+        const tasks = await loadAllTasks(ctx);
+        const tasksByRef = buildTaskStatusMap(tasks);
+
+        // Apply status filter
+        let filtered: LoadedPlan[] = plans;
+        if (query.status) {
+          const statusFilters = Array.isArray(query.status) ? query.status : [query.status];
+          filtered = filtered.filter((plan) => statusFilters.includes(plan.status));
+        }
+
+        // Sort by created_at descending (newest first)
+        const sorted = [...filtered].sort(
+          (a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime()
+        );
+
+        // AC: @ui-plans-view ac-1 - Compute progress for each plan
+        const items: PlanSummary[] = sorted.map((plan) => toPlanSummary(plan, tasksByRef));
+
+        return {
+          items,
+          total: items.length,
+        };
+      },
+      {
+        query: t.Object({
+          status: t.Optional(t.Union([t.String(), t.Array(t.String())])),
+        }),
+      }
+    )
+    // AC: @ui-plans-view ac-2 - Get single plan with content (lazy-loaded by UI on expand)
+    .get(
+      '/:ref',
+      async ({ params, error: errorResponse, projectContext }) => {
+        const ctx = await initContext(projectContext.path);
+        const plan = await findPlanByRef(ctx, params.ref);
+
+        if (!plan) {
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Plan reference "${params.ref}" not found`,
+            suggestion: 'Use kspec plan list to find valid plan references',
+          });
+        }
+
+        const tasks = await loadAllTasks(ctx);
+        const tasksByRef = buildTaskStatusMap(tasks);
+
+        const detail: PlanDetail = {
+          ...toPlanSummary(plan, tasksByRef),
+          content: plan.content,
+        };
+
+        return detail;
+      }
+    );
+}

package/dist/daemon/routes/projects.ts

@@ -20,10 +20,14 @@ import type { ProjectContextManager } from '../project-context';
 
 interface ProjectsRouteOptions {
   projectManager: ProjectContextManager;
+  /** Called after a project is registered (e.g., to start session sync). */
+  onProjectRegistered?: (projectPath: string) => Promise<void>;
+  /** Called before a project is unregistered (e.g., to stop session sync). */
+  onProjectUnregistered?: (projectPath: string) => void;
 }
 
 export function createProjectsRoutes(options: ProjectsRouteOptions) {
-  const { projectManager } = options;
+  const { projectManager, onProjectRegistered, onProjectUnregistered } = options;
 
   return new Elysia({ prefix: '/api/projects' })
     // AC: @multi-directory-daemon ac-28 - List registered projects
@@ -91,6 +95,16 @@ export function createProjectsRoutes(options: ProjectsRouteOptions) {
             throw error;
           }
 
+          // Start session sync for the newly registered project
+          if (onProjectRegistered) {
+            try {
+              await onProjectRegistered(context.path);
+            } catch (error) {
+              // Session sync init failure does not block project registration
+              console.error(`[daemon] Failed to start session sync for ${context.path}:`, error);
+            }
+          }
+
           return {
             success: true,
             project: {
@@ -135,23 +149,31 @@ export function createProjectsRoutes(options: ProjectsRouteOptions) {
       // AC: @multi-directory-daemon ac-30 - Decode path from URL parameter
       const projectPath = decodeURIComponent(params.encodedPath);
 
-      // Validate project exists
-      if (!projectManager.hasProject(projectPath)) {
+      // Validate project exists and get normalized context
+      let context;
+      try {
+        context = projectManager.getProject(projectPath);
+      } catch {
         return errorResponse(404, {
           error: `Project not registered: ${projectPath}`,
         });
       }
 
       try {
+        // Stop session sync before unregistering (use normalized path)
+        if (onProjectUnregistered) {
+          onProjectUnregistered(context.path);
+        }
+
         // AC: @multi-directory-daemon ac-30 - Stop file watcher
-        await projectManager.stopWatcher(projectPath);
+        await projectManager.stopWatcher(context.path);
 
         // AC: @multi-directory-daemon ac-30 - Unregister project
-        projectManager.unregisterProject(projectPath);
+        projectManager.unregisterProject(context.path);
 
         return {
           success: true,
-          message: `Project unregistered: ${projectPath}`,
+          message: `Project unregistered: ${context.path}`,
         };
       } catch (error: unknown) {
         return errorResponse(500, {

package/dist/daemon/routes/ref-resolution.ts

@@ -0,0 +1,119 @@
+/**
+ * Reference Resolution Utilities
+ *
+ * Server-side resolution of @references to display-ready metadata.
+ * Used by API routes to include resolved titles alongside raw refs.
+ *
+ * AC: @ui-api-ref-resolution ac-1, ac-2, ac-3
+ */
+
+import type { ReferenceIndex } from '../../parser/index.js';
+
+/**
+ * Resolved metadata for a single-valued reference.
+ * AC: @ui-api-ref-resolution ac-1
+ */
+export interface ResolvedRef {
+  ref: string;
+  title: string | null;
+}
+
+/**
+ * Resolved metadata for an array reference entry with status.
+ * AC: @ui-api-ref-resolution ac-2
+ */
+export interface ResolvedRefEntry {
+  ref: string;
+  title: string | null;
+  status: string | null;
+}
+
+/**
+ * Lightweight index entry for the ref index endpoint.
+ * AC: @ui-api-ref-resolution ac-4, ac-5
+ */
+export interface RefIndexEntry {
+  title: string;
+  type: string;
+  status?: string;
+}
+
+/**
+ * Resolve a single-valued reference to its title.
+ * Returns null title if the ref cannot be resolved (ac-3).
+ *
+ * AC: @ui-api-ref-resolution ac-1, ac-3
+ */
+export function resolveRefTitle(
+  index: ReferenceIndex,
+  ref: string | undefined | null,
+): string | null {
+  if (!ref) return null;
+  const result = index.resolve(ref);
+  if (!result.ok) return null;
+  const item = result.item as { title?: string };
+  return item.title ?? null;
+}
+
+/**
+ * Resolve an array of references to entries with title and status.
+ * Invalid/deleted refs get null title but preserve the raw ref (ac-3).
+ *
+ * AC: @ui-api-ref-resolution ac-2, ac-3
+ */
+export function resolveRefEntries(
+  index: ReferenceIndex,
+  refs: string[] | undefined | null,
+): ResolvedRefEntry[] {
+  if (!refs || refs.length === 0) return [];
+  return refs.map((ref) => {
+    const result = index.resolve(ref);
+    if (!result.ok) {
+      return { ref, title: null, status: null };
+    }
+    const item = result.item as { title?: string; status?: string };
+    return {
+      ref,
+      title: item.title ?? null,
+      status: item.status ?? null,
+    };
+  });
+}
+
+/**
+ * Build a lightweight ref index map for the index endpoint.
+ * Includes both ULID and slug keys for each entity.
+ *
+ * AC: @ui-api-ref-resolution ac-4, ac-5
+ */
+export function buildRefIndex(
+  index: ReferenceIndex,
+): Record<string, RefIndexEntry> {
+  const result: Record<string, RefIndexEntry> = {};
+
+  for (const ulid of index.getAllUlids()) {
+    const item = index.getByUlid(ulid);
+    if (!item) continue;
+
+    const typed = item as { title?: string; type?: string; status?: string; slugs?: string[] };
+    if (!typed.title) continue;
+
+    const entry: RefIndexEntry = {
+      title: typed.title,
+      type: typed.type ?? 'unknown',
+      ...(typed.status ? { status: typed.status } : {}),
+    };
+
+    // Index by ULID
+    result[ulid] = entry;
+
+    // Index by slugs
+    if (typed.slugs) {
+      for (const slug of typed.slugs) {
+        result[slug] = entry;
+      }
+    }
+  }
+
+  return result;
+}

package/dist/daemon/routes/refs.ts

@@ -0,0 +1,42 @@
+/**
+ * Ref Index API Route
+ *
+ * Lightweight endpoint for resolving arbitrary refs to display metadata.
+ * Returns a map of all resolvable refs (tasks, items, traits) with
+ * title, type, and status. Both ULID and slug keys are included.
+ *
+ * AC Coverage:
+ * - @ui-api-ref-resolution ac-4: Returns map of all resolvable refs with display metadata
+ * - @ui-api-ref-resolution ac-5: Payload is significantly smaller than full entity lists
+ * - @trait-api-endpoint ac-1: Returns 2xx with JSON body
+ * - @trait-api-endpoint ac-6: Includes X-Request-Id header (via middleware)
+ */
+
+import { Elysia } from 'elysia';
+import {
+  initContext,
+  loadAllTasks,
+  loadAllItems,
+  loadPlans,
+  ReferenceIndex,
+} from '../../parser/index.js';
+import { buildRefIndex } from './ref-resolution.js';
+
+export function createRefsRoutes() {
+  return new Elysia({ prefix: '/api/refs' })
+
+    // AC: @ui-api-ref-resolution ac-4, ac-5 - Lightweight ref index endpoint
+    // AC: @trait-api-endpoint ac-1 - Returns 2xx with JSON body
+    .get('/', async ({ projectContext }) => {
+      const ctx = await initContext(projectContext.path);
+      const [tasks, items, plans] = await Promise.all([
+        loadAllTasks(ctx),
+        loadAllItems(ctx),
+        loadPlans(ctx),
+      ]);
+      const index = new ReferenceIndex(tasks, items, [], plans);
+      const refs = buildRefIndex(index);
+
+      return { refs };
+    });
+}

package/dist/daemon/routes/session-related.ts

@@ -0,0 +1,140 @@
+import {
+  AlignmentIndex,
+  ReferenceIndex,
+  type LoadedSpecItem,
+  type LoadedTask,
+} from '../../parser/index.js';
+import { getSessionCache } from '../../sessions/cache.js';
+import type { SessionLogSummary } from '../../sessions/store.js';
+
+interface RelatedSessionsNotFound {
+  error: 'not_found';
+  message: string;
+  suggestion: string;
+}
+
+function sortSessions(sessions: SessionLogSummary[]): SessionLogSummary[] {
+  return [...sessions].sort(
+    (a, b) => new Date(b.started_at).getTime() - new Date(a.started_at).getTime()
+  );
+}
+
+function buildTaskRefSet(task: Pick<LoadedTask, '_ulid' | 'slugs'>): Set<string> {
+  const refs = new Set<string>([task._ulid, `@${task._ulid}`]);
+  for (const slug of task.slugs) {
+    refs.add(slug);
+    refs.add(`@${slug}`);
+  }
+  return refs;
+}
+
+function filterSessionsByTaskRefs(
+  sessions: SessionLogSummary[],
+  taskRefs: Set<string>
+): SessionLogSummary[] {
+  return sessions.filter((session) => {
+    if (!session.task_id) return false;
+    const taskId = session.task_id.startsWith('@')
+      ? session.task_id.slice(1)
+      : session.task_id;
+    return taskRefs.has(taskId) || taskRefs.has(session.task_id);
+  });
+}
+
+export async function getRelatedSessionsForTask(params: {
+  items: LoadedSpecItem[];
+  tasks: LoadedTask[];
+  taskRef: string;
+  sessionsDir: string;
+}): Promise<
+  | { sessions: SessionLogSummary[]; task: LoadedTask }
+  | { error: RelatedSessionsNotFound }
+> {
+  const { items, tasks, taskRef, sessionsDir } = params;
+  const refIndex = new ReferenceIndex(tasks, items);
+  const resolved = refIndex.resolve(taskRef);
+
+  if (!resolved.ok) {
+    return {
+      error: {
+        error: 'not_found',
+        message: `Task reference "${taskRef}" not found`,
+        suggestion: 'Use GET /api/tasks or kspec task list to find valid task references',
+      },
+    };
+  }
+
+  const task = tasks.find((candidate) => candidate._ulid === resolved.ulid);
+  if (!task) {
+    return {
+      error: {
+        error: 'not_found',
+        message: `Reference "${taskRef}" is not a task`,
+        suggestion: 'This reference might point to a spec item instead',
+      },
+    };
+  }
+
+  const sessionCache = getSessionCache(sessionsDir);
+  const sessions = await sessionCache.getAll(sessionsDir);
+  const filtered = filterSessionsByTaskRefs(sessions, buildTaskRefSet(task));
+
+  return {
+    task,
+    sessions: sortSessions(filtered),
+  };
+}
+
+export async function getRelatedSessionsForItem(params: {
+  itemRef: string;
+  items: LoadedSpecItem[];
+  tasks: LoadedTask[];
+  sessionsDir: string;
+}): Promise<
+  | { item: LoadedSpecItem; sessions: SessionLogSummary[] }
+  | { error: RelatedSessionsNotFound }
+> {
+  const { itemRef, items, tasks, sessionsDir } = params;
+  const refIndex = new ReferenceIndex(tasks, items);
+  const alignmentIndex = new AlignmentIndex(tasks, items);
+  alignmentIndex.buildLinks(refIndex);
+
+  const resolved = refIndex.resolve(itemRef);
+  if (!resolved.ok) {
+    return {
+      error: {
+        error: 'not_found',
+        message: `Item reference "${itemRef}" not found`,
+        suggestion: 'Use GET /api/items or kspec item list to find valid item references',
+      },
+    };
+  }
+
+  const item = items.find((candidate) => candidate._ulid === resolved.ulid);
+  if (!item) {
+    return {
+      error: {
+        error: 'not_found',
+        message: `Reference "${itemRef}" is not a spec item`,
+        suggestion: 'This reference might point to a task instead',
+      },
+    };
+  }
+
+  const linkedTasks = alignmentIndex.getTasksForSpec(resolved.ulid);
+  const taskRefs = new Set<string>();
+  for (const task of linkedTasks) {
+    for (const ref of buildTaskRefSet(task)) {
+      taskRefs.add(ref);
+    }
+  }
+
+  const sessionCache = getSessionCache(sessionsDir);
+  const sessions = await sessionCache.getAll(sessionsDir);
+  const filtered = filterSessionsByTaskRefs(sessions, taskRefs);
+
+  return {
+    item,
+    sessions: sortSessions(filtered),
+  };
+}