@dain-os/mcp-server 0.9.1 → 0.10.0

package/dist/tools/cadence.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from './types.js';
+/** All four Cadence MCP tools. */
+export declare const cadenceTools: ToolDefinition[];
+//# sourceMappingURL=cadence.d.ts.map

package/dist/tools/cadence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cadence.d.ts","sourceRoot":"","sources":["../../src/tools/cadence.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAoRjD,kCAAkC;AAClC,eAAO,MAAM,YAAY,EAAE,cAAc,EAKxC,CAAC"}

package/dist/tools/cadence.js

@@ -0,0 +1,245 @@
+import { z } from 'zod';
+/**
+ * Cadence MCP tools: AI agent feed for the Sprint + Cadence feature.
+ *
+ * Four tools for agents (Claude Code, Otto) to interact with the sprint plan:
+ *   claim_next_task       — fetch the highest-ranked open task from the sprint
+ *   report_task_progress  — append a one-liner progress note with agent identity
+ *   mark_blocked          — flag a task as blocked with a reason
+ *   request_unblock       — signal that a task needs human attention to unblock
+ *
+ * Audit trail: all writes carry metadata.via='mcp' and metadata.client so the
+ * cadence_actions record shows "Claude Code" rather than "system". The API
+ * side uses this to attribute agent activity in the sprint timeline.
+ *
+ * @builder ship-api-builder (Round 4, R4-T1)
+ */
+// ---------------------------------------------------------------------------
+// claim_next_task
+// ---------------------------------------------------------------------------
+const claimNextTask = {
+    name: 'claim_next_task',
+    description: 'Fetch the highest-ranked open task from the Cadence sprint feed. ' +
+        'Returns the task object with its Cadence ranking rationale and score. ' +
+        'Call this at the start of an autonomous work session to find what to work on next. ' +
+        'Filters by sprintId, projectId, or assigneeId when provided.',
+    inputSchema: z.object({
+        sprintId: z
+            .string()
+            .uuid()
+            .optional()
+            .describe('Restrict to tasks in a specific sprint.'),
+        projectId: z
+            .string()
+            .uuid()
+            .optional()
+            .describe('Restrict to tasks in a specific project.'),
+        assigneeId: z
+            .string()
+            .uuid()
+            .optional()
+            .describe('Restrict to tasks assigned to a specific IAM user.'),
+        client: z
+            .string()
+            .max(100)
+            .optional()
+            .describe('Caller identity for the audit trail (e.g. "claude-code", "otto"). ' +
+            'Logged as metadata.client on the resulting cadence_actions row.'),
+    }),
+    handler: async (client, input) => {
+        const params = new URLSearchParams();
+        if (input.sprintId)
+            params.set('sprintId', input.sprintId);
+        if (input.projectId)
+            params.set('projectId', input.projectId);
+        if (input.assigneeId)
+            params.set('assigneeId', input.assigneeId);
+        const query = params.toString() ? `?${params.toString()}` : '';
+        // GET /api/v1/cadence/feed/next-task returns { task: RankedTask | null }
+        // The ranked task includes rationale and ranking score from CadenceRankerService.
+        return client.get(`/cadence/feed/next-task${query}`);
+    },
+};
+// ---------------------------------------------------------------------------
+// report_task_progress
+// ---------------------------------------------------------------------------
+const reportTaskProgress = {
+    name: 'report_task_progress',
+    description: 'Append a one-line progress note to a task and record it in the Cadence audit trail. ' +
+        'Use this after completing a meaningful unit of work on a task (e.g. "Implemented ' +
+        'the migration file and ran npx prisma generate"). ' +
+        'The note is written to the task\'s AI progress log section and creates a ' +
+        'cadence_actions row with action_type=progress_note for the sprint timeline. ' +
+        'Provide your client identity so the audit trail reads "Claude Code" not "system".',
+    inputSchema: z.object({
+        taskId: z
+            .string()
+            .uuid()
+            .describe('The task to update.'),
+        note: z
+            .string()
+            .min(1)
+            .max(500)
+            .describe('One-line progress note in plain English. ' +
+            'Will be appended inside the AI-progress-log sentinel block in the task description. ' +
+            'Example: "Added Zod schema and controller handler for POST /cadence/draft."'),
+        client: z
+            .string()
+            .max(100)
+            .optional()
+            .describe('Caller identity for the audit trail (e.g. "claude-code"). ' +
+            'Logged as metadata.client on the cadence_actions row.'),
+    }),
+    handler: async (client, input) => {
+        // Step 1: fetch the current task description so we can append to the AI progress block.
+        const task = await client.get(`/tasks/${input.taskId}`);
+        const now = new Date().toISOString();
+        const clientLabel = input.client ?? 'mcp-agent';
+        const newLine = `[${now}] (${clientLabel}) ${input.note}`;
+        const BEGIN_MARKER = '<!-- BEGIN AI-PROGRESS-LOG -->';
+        const END_MARKER = '<!-- END AI-PROGRESS-LOG -->';
+        const existing = task.description ?? '';
+        let updatedDescription;
+        if (existing.includes(BEGIN_MARKER) && existing.includes(END_MARKER)) {
+            // Append before the closing marker.
+            updatedDescription = existing.replace(END_MARKER, `${newLine}\n${END_MARKER}`);
+        }
+        else {
+            // No sentinel block yet — append one at the end.
+            updatedDescription =
+                existing.trimEnd() +
+                    `\n\n${BEGIN_MARKER}\n${newLine}\n${END_MARKER}`;
+        }
+        // Step 2: update the task description.
+        await client.put(`/tasks/${input.taskId}`, { description: updatedDescription });
+        // Step 3: write a cadence_actions row for the sprint timeline.
+        // action_type='progress_note', target_type='task', payload carries the note + client identity.
+        await client.post('/cadence/actions', {
+            actionType: 'progress_note',
+            targetType: 'task',
+            targetId: input.taskId,
+            rationale: input.note,
+            payload: {
+                via: 'mcp',
+                client: clientLabel,
+                timestamp: now,
+            },
+        });
+        return { success: true, taskId: input.taskId, note: input.note };
+    },
+};
+// ---------------------------------------------------------------------------
+// mark_blocked
+// ---------------------------------------------------------------------------
+const markBlocked = {
+    name: 'mark_blocked',
+    description: 'Mark a task as blocked and record the reason in the Cadence audit trail. ' +
+        'Use when you hit a genuine blocker while working on a task autonomously ' +
+        '(e.g. missing API key, conflicting schema, waiting on another task). ' +
+        'The task status changes to "blocked" and a cadence_actions row is created ' +
+        'so the sprint timeline shows the block and the human can address it. ' +
+        'The reason must be specific enough for a human to act on without asking you.',
+    inputSchema: z.object({
+        taskId: z
+            .string()
+            .uuid()
+            .describe('The task to mark blocked.'),
+        reason: z
+            .string()
+            .min(1)
+            .max(500)
+            .describe('Plain English description of the blocker. Be specific: ' +
+            '"Waiting on OPENAI_API_KEY in the api .env" is actionable. ' +
+            '"It\'s blocked" is not. Minimum 1 character, maximum 500.'),
+        client: z
+            .string()
+            .max(100)
+            .optional()
+            .describe('Caller identity for the audit trail (e.g. "claude-code").'),
+    }),
+    handler: async (client, input) => {
+        const clientLabel = input.client ?? 'mcp-agent';
+        const now = new Date().toISOString();
+        // Step 1: update task status to blocked.
+        await client.put(`/tasks/${input.taskId}`, { status: 'blocked' });
+        // Step 2: create a cadence_actions row for the audit trail.
+        await client.post('/cadence/actions', {
+            actionType: 'mark_blocked',
+            targetType: 'task',
+            targetId: input.taskId,
+            rationale: input.reason,
+            payload: {
+                via: 'mcp',
+                client: clientLabel,
+                timestamp: now,
+                reason: input.reason,
+            },
+        });
+        return { success: true, taskId: input.taskId, reason: input.reason };
+    },
+};
+// ---------------------------------------------------------------------------
+// request_unblock
+// ---------------------------------------------------------------------------
+const requestUnblock = {
+    name: 'request_unblock',
+    description: 'Signal that a blocked task needs human attention to unblock. ' +
+        'Use after mark_blocked if you want to escalate urgency or add additional context ' +
+        'beyond the original block reason. ' +
+        'Creates a cadence_actions row with action_type=request_unblock which surfaces ' +
+        'in the next Cadence daily scan and CadenceSidebarPanel stale items list. ' +
+        'Does not change task status (task stays blocked until a human acts).',
+    inputSchema: z.object({
+        taskId: z
+            .string()
+            .uuid()
+            .describe('The blocked task that needs human attention.'),
+        context: z
+            .string()
+            .min(1)
+            .max(500)
+            .optional()
+            .describe('Additional context for the human — e.g. what you tried, what you need to proceed. ' +
+            'Optional but strongly recommended for actionability.'),
+        client: z
+            .string()
+            .max(100)
+            .optional()
+            .describe('Caller identity for the audit trail (e.g. "claude-code").'),
+    }),
+    handler: async (client, input) => {
+        const clientLabel = input.client ?? 'mcp-agent';
+        const now = new Date().toISOString();
+        // Write a cadence_actions row with action_type='request_unblock'.
+        // The next daily scan will pick this up and surface it in the stale items list.
+        await client.post('/cadence/actions', {
+            actionType: 'request_unblock',
+            targetType: 'task',
+            targetId: input.taskId,
+            rationale: input.context ?? 'Agent requested human unblock.',
+            payload: {
+                via: 'mcp',
+                client: clientLabel,
+                timestamp: now,
+                context: input.context ?? null,
+            },
+        });
+        return {
+            success: true,
+            taskId: input.taskId,
+            message: 'Unblock request recorded. The next Cadence daily scan will surface this task ' +
+                'in the sprint sidebar for human review.',
+        };
+    },
+};
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+/** All four Cadence MCP tools. */
+export const cadenceTools = [
+    claimNextTask,
+    reportTaskProgress,
+    markBlocked,
+    requestUnblock,
+];
+//# sourceMappingURL=cadence.js.map

package/dist/tools/cadence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cadence.js","sourceRoot":"","sources":["../../src/tools/cadence.ts"],"names":[],"mappings":"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"}

package/dist/tools/comments.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from './types.js';
+export declare const commentTools: ToolDefinition[];
+//# sourceMappingURL=comments.d.ts.map

package/dist/tools/comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../../src/tools/comments.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAoBjD,eAAO,MAAM,YAAY,EAAE,cAAc,EAAqB,CAAC"}

package/dist/tools/comments.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+const addTaskComment = {
+    name: 'add_task_comment',
+    description: 'Add a comment to a task. Comments are internal by default (visible to the workspace, not to clients on the portal). Pass isInternal: false to make the comment client-visible.',
+    inputSchema: z.object({
+        taskId: z.string().uuid(),
+        content: z.string().min(1).max(10000),
+        isInternal: z
+            .boolean()
+            .optional()
+            .describe('Defaults to true. Set false to make the comment client-visible.'),
+    }),
+    handler: async (client, input) => {
+        const { taskId, ...body } = input;
+        return client.post(`/tasks/${taskId}/comments`, body);
+    },
+};
+export const commentTools = [addTaskComment];
+//# sourceMappingURL=comments.js.map

package/dist/tools/comments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.js","sourceRoot":"","sources":["../../src/tools/comments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,cAAc,GAAmB;IACrC,IAAI,EAAE,kBAAkB;IACxB,WAAW,EACT,gLAAgL;IAClL,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;QACzB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;QACrC,UAAU,EAAE,CAAC;aACV,OAAO,EAAE;aACT,QAAQ,EAAE;aACV,QAAQ,CAAC,iEAAiE,CAAC;KAC/E,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE;QAC/B,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;QAClC,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,MAAM,WAAW,EAAE,IAAI,CAAC,CAAC;IACxD,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAqB,CAAC,cAAc,CAAC,CAAC"}

package/dist/tools/developer.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from './types.js';
+export declare const developerTools: ToolDefinition[];
+//# sourceMappingURL=developer.d.ts.map

package/dist/tools/developer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"developer.d.ts","sourceRoot":"","sources":["../../src/tools/developer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAyXjD,eAAO,MAAM,cAAc,EAAE,cAAc,EAW1C,CAAC"}

package/dist/tools/developer.js

@@ -0,0 +1,349 @@
+import { z } from 'zod';
+import { logTimeEntryTool } from './log-time-entry.js';
+/**
+ * Developer KB tools. Five operations: log_changelog_entry, log_session_context,
+ * log_knowledge_base_entry, list_recent_sessions, search_knowledge_base.
+ *
+ * These back the /wrapup, /recap, and /dev-kb slash commands. The slash command
+ * still does the conversation analysis (parsing decisions, lessons, etc.); the
+ * tools here are the persistence + retrieval surface. With these in place a
+ * developer needs only the DainOS MCP installed — no Supabase MCP token — and
+ * the workflows port to any MCP client (Cursor, Continue, etc.).
+ *
+ * All tools are cross-project: the caller supplies `project` (e.g. "dain-os",
+ * "herbert", "mabel") on every call. The backing tables live in the developer
+ * schema and span tenants.
+ */
+/**
+ * Some MCP clients serialise array-typed tool arguments as JSON-encoded strings
+ * rather than nested arrays. Caught during /wrapup on 2026-05-14:
+ * `log_changelog_entry` rejected a perfectly-shaped batch with "expected array,
+ * received string" while `log_knowledge_base_entry` accepted the same shape.
+ * The difference was the model's serialisation choice on that specific tool
+ * call, not the schema. Defending the entries field at the parse boundary
+ * makes both spellings work.
+ */
+function jsonStringArray(item, min = 1, max = 50) {
+    return z.preprocess((val) => {
+        if (typeof val === 'string') {
+            try {
+                return JSON.parse(val);
+            }
+            catch {
+                return val;
+            }
+        }
+        return val;
+    }, z.array(item).min(min).max(max));
+}
+/**
+ * Optional string that also accepts `null`. Some clients send `null` for
+ * "field intentionally absent" rather than omitting the key; the previous
+ * `z.string().optional()` rejected null with "expected string, received null".
+ */
+const optionalString = z.preprocess((val) => (val === null ? undefined : val), z.string().optional());
+/** Optional non-string field (e.g. number, boolean, array) that accepts null too. */
+function nullishOptional(schema) {
+    return z.preprocess((val) => (val === null ? undefined : val), schema.optional());
+}
+const commitTypeEnum = z.enum([
+    'feat', 'fix', 'chore', 'refactor', 'test', 'docs', 'perf', 'ci', 'build', 'revert', 'style',
+]);
+const sourceTypeEnum = z.enum([
+    'fix_commit', 'pr_comment', 'pr_review', 'code_review',
+    'ai_conversation', 'incident', 'documentation', 'debugging_session',
+]);
+const severityEnum = z.enum(['critical', 'high', 'medium', 'low']);
+const kbCategoryEnum = z.enum(['gotcha', 'pattern', 'lesson', 'decision', 'workaround']);
+// ---------------------------------------------------------------------------
+// log_changelog_entry — batch insert of commit records
+// ---------------------------------------------------------------------------
+const changelogEntrySchema = z.object({
+    commit_sha: z.string().length(40).describe('Full 40-character SHA.'),
+    branch: optionalString.describe('Defaults to "main" if omitted.'),
+    commit_type: commitTypeEnum.describe('Conventional-commit type prefix.'),
+    scope: optionalString,
+    summary: z.string().describe('Commit message subject line.'),
+    description: optionalString,
+    files_changed: nullishOptional(z.coerce.number().int()),
+    insertions: nullishOptional(z.coerce.number().int()),
+    deletions: nullishOptional(z.coerce.number().int()),
+    milestone: optionalString,
+    task_ref: optionalString.describe('Linear / Jira / Notion task id.'),
+    impacts_config: nullishOptional(z.boolean()).describe('Defaults false.'),
+    breaking_change: nullishOptional(z.boolean()).describe('Defaults false.'),
+    tags: nullishOptional(z.array(z.string())),
+    author: optionalString,
+    committed_at: z.string().describe('ISO 8601 timestamp.'),
+    pr_number: nullishOptional(z.coerce.number().int()),
+    pr_url: optionalString,
+});
+const logChangelogEntry = {
+    name: 'log_changelog_entry',
+    description: 'Append commit records to the developer changelog for a project. Use during /wrapup to persist today\'s commits. Accepts a batch (1-50 entries). Idempotent on (project, commit_sha): duplicates are silently skipped. Returns { inserted, skipped } counts.',
+    inputSchema: z.object({
+        project: z.string().describe('Project slug, e.g. "dain-os", "herbert", "mabel".'),
+        entries: jsonStringArray(changelogEntrySchema, 1, 50),
+    }),
+    handler: async (client, input) => {
+        const entries = input.entries.map((entry) => ({
+            ...entry,
+            project: input.project,
+        }));
+        return client.post('/developer/changelog', { entries });
+    },
+};
+// ---------------------------------------------------------------------------
+// log_session_context — single session insert
+// ---------------------------------------------------------------------------
+const decisionSchema = z.object({
+    decision: z.string(),
+    reason: z.string(),
+});
+const logSessionContext = {
+    name: 'log_session_context',
+    description: 'Record a single development session for a project (one row per session). Captures decisions made, files touched, blockers, and handoff notes. Use during /wrapup to leave breadcrumbs for the next session. Read back via list_recent_sessions during /recap.',
+    inputSchema: z.object({
+        project: z.string().describe('Project slug, e.g. "dain-os".'),
+        session_name: z.string().describe('Short descriptive title.'),
+        session_date: optionalString.describe('YYYY-MM-DD. Defaults to today server-side.'),
+        operator: z.string().describe('e.g. "Dane + Claude Opus 4.7".'),
+        machine: optionalString,
+        duration_minutes: nullishOptional(z.coerce.number().int()),
+        summary: z.string().describe('2-4 sentence overview of WHAT and WHY.'),
+        decisions_made: nullishOptional(z.array(decisionSchema)).describe('Non-obvious choices future sessions need to understand.'),
+        files_touched: nullishOptional(z.array(z.string())),
+        tasks_completed: nullishOptional(z.array(z.string())),
+        blockers: nullishOptional(z.array(z.string())),
+        handoff_notes: optionalString.describe('What the next session needs to know first.'),
+        tags: nullishOptional(z.array(z.string())),
+        client_visible: nullishOptional(z.boolean()).describe('When false, the session is hidden from portal product pages and the client portal activity feed. Defaults to true. Set false for sensitive sessions (security incidents, internal escalations).'),
+        product_id: nullishOptional(z.string().uuid()).describe('UUID of the product this session relates to.'),
+        task_ids: nullishOptional(z.array(z.string().uuid()).max(100)).describe('UUIDs of DainOS tasks worked on during the session (max 100).'),
+        operator_iam_user_id: nullishOptional(z.string().uuid()).describe('IAM user UUID of the operator. Resolved server-side from the auth token when omitted.'),
+    }),
+    handler: async (client, input) => client.post('/developer/sessions', input),
+};
+// ---------------------------------------------------------------------------
+// log_knowledge_base_entry — batch insert of KB findings
+// ---------------------------------------------------------------------------
+const kbEntrySchema = z.object({
+    category: kbCategoryEnum,
+    module: z.string().describe('System / area, e.g. "auth", "react", "prisma".'),
+    title: z.string().describe('Short descriptive title.'),
+    description: z.string().describe('What happened / what is this.'),
+    impact: optionalString.describe('What goes wrong if you don\'t know this.'),
+    prevention: optionalString.describe('How to avoid it next time.'),
+    severity: nullishOptional(severityEnum),
+    source_type: sourceTypeEnum,
+    source_refs: nullishOptional(z.array(z.string())).describe('Links, file paths, or commit SHAs.'),
+    tags: nullishOptional(z.array(z.string())),
+    platform: optionalString.describe('e.g. "supabase", "anthropic", "vercel".'),
+});
+const logKnowledgeBaseEntry = {
+    name: 'log_knowledge_base_entry',
+    description: 'Append KB findings (gotchas, patterns, lessons, decisions, workarounds) for a project. Only add entries for things that were SURPRISING, NON-OBVIOUS, or caused real problems. Use during /wrapup. Accepts a batch (1-50 entries). Check for similar existing titles via search_knowledge_base before adding to avoid duplicates.',
+    inputSchema: z.object({
+        project: z.string().describe('Project slug, e.g. "dain-os". Use "universal" for cross-product lessons.'),
+        entries: jsonStringArray(kbEntrySchema, 1, 50),
+    }),
+    handler: async (client, input) => {
+        const entries = input.entries.map((entry) => ({
+            ...entry,
+            project: input.project,
+        }));
+        return client.post('/developer/knowledge-base', { entries });
+    },
+};
+// ---------------------------------------------------------------------------
+// list_recent_sessions — read recent sessions for /recap
+// ---------------------------------------------------------------------------
+const listRecentSessions = {
+    name: 'list_recent_sessions',
+    description: 'List the most recent development sessions for a project, newest first. Use during /recap to brief the user on what happened in the last 1-N sessions. Returns full session_context rows including decisions, blockers, and handoff_notes.',
+    inputSchema: z.object({
+        project: z.string().describe('Project slug.'),
+        limit: z.coerce.number().int().min(1).max(50).optional().describe('Default 10, max 50.'),
+        offset: z.coerce.number().int().min(0).optional().describe('For pagination.'),
+    }),
+    handler: async (client, input) => {
+        const params = new URLSearchParams();
+        params.set('project', input.project);
+        if (input.limit !== undefined)
+            params.set('limit', String(input.limit));
+        if (input.offset !== undefined)
+            params.set('offset', String(input.offset));
+        return client.get(`/developer/sessions?${params.toString()}`);
+    },
+};
+// ---------------------------------------------------------------------------
+// search_knowledge_base — read KB by project/module/severity/keyword
+// ---------------------------------------------------------------------------
+const searchKnowledgeBase = {
+    name: 'search_knowledge_base',
+    description: 'Search the developer KB for relevant gotchas, patterns, lessons, decisions, and workarounds. Use before writing code in a module (catches existing gotchas), during /dev-kb invocations, and before /wrapup to dedupe. Filters AND together; `q` is a case-insensitive substring match against title and description.',
+    inputSchema: z.object({
+        project: z.string().describe('Project slug. Filter by "universal" for cross-product entries.'),
+        module: z.string().optional().describe('e.g. "auth", "react", "prisma".'),
+        category: kbCategoryEnum.optional(),
+        severity: severityEnum.optional(),
+        q: z.string().optional().describe('Free-text match against title + description.'),
+        limit: z.coerce.number().int().min(1).max(50).optional().describe('Default 10.'),
+        offset: z.coerce.number().int().min(0).optional(),
+    }),
+    handler: async (client, input) => {
+        const params = new URLSearchParams();
+        params.set('project', input.project);
+        if (input.module)
+            params.set('module', input.module);
+        if (input.category)
+            params.set('category', input.category);
+        if (input.severity)
+            params.set('severity', input.severity);
+        if (input.q)
+            params.set('q', input.q);
+        if (input.limit !== undefined)
+            params.set('limit', String(input.limit));
+        if (input.offset !== undefined)
+            params.set('offset', String(input.offset));
+        return client.get(`/developer/knowledge-base/search?${params.toString()}`);
+    },
+};
+// ---------------------------------------------------------------------------
+// update_* — partial edits to existing developer KB rows
+// ---------------------------------------------------------------------------
+//
+// Wraps PATCH /developer/{changelog|sessions|knowledge-base}/:id. Used when a
+// /wrapup-style flow needs to amend a previously-logged entry (e.g. the user
+// corrects a session summary, fills in handoff_notes after the fact, or
+// reclassifies a KB entry's severity). `project` is immutable on every row —
+// to "move" between projects, delete and re-insert.
+const updateChangelogEntry = {
+    name: 'update_changelog_entry',
+    description: 'Partially update an existing changelog entry by id. Every field is optional; only the supplied fields are written. `project` and `commit_sha` are immutable. Returns the refreshed row. 404 if id is unknown.',
+    inputSchema: z.object({
+        id: z.string().uuid().describe('Changelog entry id (UUID).'),
+        branch: optionalString,
+        commit_type: commitTypeEnum.optional(),
+        scope: optionalString,
+        summary: optionalString,
+        description: optionalString,
+        files_changed: nullishOptional(z.coerce.number().int()),
+        insertions: nullishOptional(z.coerce.number().int()),
+        deletions: nullishOptional(z.coerce.number().int()),
+        milestone: optionalString,
+        task_ref: optionalString,
+        impacts_config: nullishOptional(z.boolean()),
+        breaking_change: nullishOptional(z.boolean()),
+        tags: nullishOptional(z.array(z.string())),
+        author: optionalString,
+        committed_at: optionalString.describe('ISO 8601 timestamp.'),
+        pr_number: nullishOptional(z.coerce.number().int()),
+        pr_url: optionalString,
+    }),
+    handler: async (client, input) => {
+        const { id, ...rest } = input;
+        // Drop undefined keys so the API only receives the fields the caller set.
+        const body = Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined));
+        return client.patch(`/developer/changelog/${id}`, body);
+    },
+};
+const updateSessionContext = {
+    name: 'update_session_context',
+    description: 'Partially update an existing session_context row by id. Every field is optional. `project` is immutable. Returns the refreshed row. 404 if id is unknown.',
+    inputSchema: z.object({
+        id: z.string().uuid().describe('Session context id (UUID).'),
+        session_name: optionalString,
+        session_date: optionalString.describe('YYYY-MM-DD.'),
+        operator: optionalString,
+        machine: optionalString,
+        duration_minutes: nullishOptional(z.coerce.number().int()),
+        summary: optionalString,
+        decisions_made: nullishOptional(z.array(decisionSchema)),
+        files_touched: nullishOptional(z.array(z.string())),
+        tasks_completed: nullishOptional(z.array(z.string())),
+        blockers: nullishOptional(z.array(z.string())),
+        handoff_notes: optionalString,
+        tags: nullishOptional(z.array(z.string())),
+        product_id: nullishOptional(z.string().uuid()).describe('UUID of the product this session relates to.'),
+        task_ids: nullishOptional(z.array(z.string().uuid()).max(100)).describe('UUIDs of DainOS tasks worked on during the session (max 100).'),
+        operator_iam_user_id: nullishOptional(z.string().uuid()).describe('IAM user UUID of the operator.'),
+    }),
+    handler: async (client, input) => {
+        const { id, ...rest } = input;
+        const body = Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined));
+        return client.patch(`/developer/sessions/${id}`, body);
+    },
+};
+const updateKnowledgeBaseEntry = {
+    name: 'update_knowledge_base_entry',
+    description: 'Partially update an existing KB entry by id. Every field is optional. `project` is immutable. Returns the refreshed row. 404 if id is unknown.',
+    inputSchema: z.object({
+        id: z.string().uuid().describe('KB entry id (UUID).'),
+        category: kbCategoryEnum.optional(),
+        module: optionalString,
+        title: optionalString,
+        description: optionalString,
+        impact: optionalString,
+        prevention: optionalString,
+        severity: nullishOptional(severityEnum),
+        source_type: sourceTypeEnum.optional(),
+        source_refs: nullishOptional(z.array(z.string())),
+        tags: nullishOptional(z.array(z.string())),
+        platform: optionalString,
+    }),
+    handler: async (client, input) => {
+        const { id, ...rest } = input;
+        const body = Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined));
+        return client.patch(`/developer/knowledge-base/${id}`, body);
+    },
+};
+// ---------------------------------------------------------------------------
+// list_changelog — read changelog entries by project slug + date
+// ---------------------------------------------------------------------------
+const listChangelog = {
+    name: 'list_changelog',
+    description: 'List developer changelog entries for a project, newest first. Optionally filter by `since` (ISO 8601 date). Default limit 50, max 200. Use during /recap to review recent commits for a project without raw SQL.',
+    inputSchema: z.object({
+        project: z
+            .string()
+            .min(1)
+            .max(100)
+            .regex(/^[a-z0-9][a-z0-9-]*$/, 'project must be a lowercase slug')
+            .describe('Project slug, e.g. "dain-os", "herbert", "mabel".'),
+        since: z
+            .string()
+            .datetime({ offset: true, message: 'since must be ISO 8601 with offset' })
+            .optional()
+            .describe('ISO 8601 timestamp with offset (e.g. 2026-05-18T00:00:00Z) — only return entries with committed_at >= this value.'),
+        limit: z.coerce
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe('Default 50, max 200.'),
+    }),
+    handler: async (client, input) => {
+        const params = new URLSearchParams();
+        params.set('project', input.project);
+        if (input.since)
+            params.set('since', input.since);
+        if (input.limit !== undefined)
+            params.set('limit', String(input.limit));
+        return client.get(`/developer/changelog?${params.toString()}`);
+    },
+};
+export const developerTools = [
+    logChangelogEntry,
+    logSessionContext,
+    logKnowledgeBaseEntry,
+    listRecentSessions,
+    searchKnowledgeBase,
+    updateChangelogEntry,
+    updateSessionContext,
+    updateKnowledgeBaseEntry,
+    listChangelog,
+    logTimeEntryTool,
+];
+//# sourceMappingURL=developer.js.map