@orboto/mcp 0.178.0

package/dist/tools/time-writes.js

@@ -0,0 +1,238 @@
+/**
+ * ORB-244 Phase C Group 2 - time-tracking tools.
+ *
+ * Three tools that wrap the existing /time/timer/* + /tickets/:id/time-entries
+ * endpoints:
+ *   - orboto_timer_start (ticketKey, description?, replace?)
+ * - orboto_timer_stop - closes the running timer; the API converts
+ *                         elapsed time into a time_entries row using the
+ *                         description set at start.
+ * - orboto_log_time - direct time-entry POST for after-the-fact
+ *                         logging (no running timer involved).
+ *
+ * Note: the wrapper's `timer-stop "note"` syntax sends a `note` field
+ * the API silently ignores - the time entry's description is whatever
+ * was set on `start`. To attach a note to a stopped session, post a
+ * comment afterwards via `orboto_comment`. The MCP tool only accepts
+ * what the API actually accepts.
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+import { resolveTicketByKey } from './shared.js';
+// ---------------------------------------------------------------------------
+// orboto_timer_start
+// ---------------------------------------------------------------------------
+export const timerStartToolConfig = {
+    title: 'Start a timer on a ticket',
+    description: 'Start the user\'s stopwatch on a ticket. If a timer is already running on a different ticket, pass replace=true to auto-stop the previous one (its elapsed time is committed to time_entries before the new timer begins). Description becomes the time entry\'s note when this timer eventually stops.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        description: z.string().optional().describe('Note for the time entry; set at start, not at stop.'),
+        replace: z.boolean().optional().describe('Stop+commit a running timer first (default: 409).'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeTimerStartHandler(client) {
+    return async ({ ticketKey, description, replace }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const body = { ticketId: ticket.id };
+        if (description)
+            body.description = description;
+        if (replace)
+            body.replace = true;
+        try {
+            const timer = await client.post('/time/timer/start', body);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Timer started on [${ticket.ticketKey}] ${ticket.title}${description ? ` - note: ${description}` : ''}`,
+                    }],
+                structuredContent: {
+                    ticketKey: ticket.ticketKey,
+                    startedAt: timer.startedAt,
+                    description: timer.description,
+                },
+            };
+        }
+        catch (err) {
+            // 409 = a timer is already running on a different ticket.
+            // Surface the API's hint about `replace` rather than letting
+            // the model guess.
+            if (err instanceof OrbotoApiError && err.status === 409) {
+                throw new Error('A timer is already running on a different ticket. Pass replace=true to commit its elapsed time and start fresh on this one.');
+            }
+            throw err;
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_timer_stop
+// ---------------------------------------------------------------------------
+export const timerStopToolConfig = {
+    title: 'Stop the running timer',
+    description: 'Stop the user\'s stopwatch. The API commits a time_entries row using the description set at start (or pause/resume), then deletes the active-timer record. Returns the duration in minutes.',
+    inputSchema: z.object({}).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeTimerStopHandler(client) {
+    return async () => {
+        try {
+            // ORB-1603 - the API stop is idempotent now: nothing-to-stop returns
+            // 200 { stopped:false } instead of a 404 (the 404 branch below stays
+            // for older servers), and laneFallback flags that the timer was found
+            // via the single-active-timer fallback after an instance-token mismatch.
+            const res = await client.post('/time/timer/stop', {});
+            if (res.stopped === false) {
+                return {
+                    content: [{ type: 'text', text: 'No active timer to stop.' }],
+                    structuredContent: { durationMinutes: 0, alreadyStopped: true },
+                };
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Timer stopped - logged ${res.durationMinutes} min.${res.laneFallback ? ' (matched via single-active-timer fallback - instance token differed from start)' : ''}`,
+                    }],
+                structuredContent: { durationMinutes: res.durationMinutes, ...(res.laneFallback ? { laneFallback: true } : {}) },
+            };
+        }
+        catch (err) {
+            if (err instanceof OrbotoApiError && err.status === 404) {
+                return {
+                    content: [{ type: 'text', text: 'No active timer to stop.' }],
+                    structuredContent: { durationMinutes: 0, alreadyStopped: true },
+                };
+            }
+            throw err;
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_log_time
+// ---------------------------------------------------------------------------
+export const logTimeToolConfig = {
+    title: 'Log a time entry on a ticket',
+    description: 'Direct time-entry POST - for "I just spent 90 minutes on this last Tuesday but forgot to start a timer". `loggedAt` defaults to now; pass an ISO datetime to back-date.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        durationMinutes: z.number().int().positive().describe('Minutes, > 0.'),
+        description: z.string().optional(),
+        loggedAt: z.string().datetime().optional().describe('ISO 8601. Default: now.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeLogTimeHandler(client) {
+    return async ({ ticketKey, durationMinutes, description, loggedAt }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const body = { durationMinutes };
+        if (description !== undefined)
+            body.description = description;
+        if (loggedAt)
+            body.loggedAt = loggedAt;
+        const entry = await client.post(`/tickets/${ticket.id}/time-entries`, body);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Logged ${entry.durationMinutes} min on [${ticket.ticketKey}]${entry.description ? ` - ${entry.description}` : ''}`,
+                }],
+            structuredContent: {
+                ticketKey: ticket.ticketKey,
+                entryId: entry.id,
+                durationMinutes: entry.durationMinutes,
+                description: entry.description,
+                loggedAt: entry.loggedAt,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_list_time_entries  (ORB-1292)
+// ---------------------------------------------------------------------------
+export const listTimeEntriesToolConfig = {
+    title: 'List a ticket\'s time entries',
+    description: 'List the time entries on a ticket (most recent first) with each entry\'s id, duration, date and agent label. Use this to FIND an over-tracked entry before fixing it with orboto_edit_time_entry / orboto_delete_time_entry.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        limit: z.number().int().positive().max(100).optional().describe('Default 25.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeListTimeEntriesHandler(client) {
+    return async ({ ticketKey, limit }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const page = await client.get(`/tickets/${ticket.id}/time-entries?limit=${limit ?? 25}`);
+        const lines = page.items.map((e) => {
+            // ORB-1368 - agentLabel already flags a known agent instance; add a
+            // bare [agent] marker for agent work with no instance label (a bot's
+            // NULL-lane entry).
+            const agentMark = e.agentLabel ? ` [${e.agentLabel}]` : (e.isAgentWork ? ' [agent]' : '');
+            return `- ${e.durationMinutes} min - ${e.loggedAt}${agentMark}${e.description ? ` - ${e.description}` : ''} (id ${e.id})`;
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: page.items.length ? `Time entries on [${ticket.ticketKey}]:\n${lines.join('\n')}` : `No time entries on [${ticket.ticketKey}].`,
+                }],
+            structuredContent: { ticketKey: ticket.ticketKey, entries: page.items, nextCursor: page.nextCursor },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_edit_time_entry  (ORB-1292)
+// ---------------------------------------------------------------------------
+export const editTimeEntryToolConfig = {
+    title: 'Edit / correct a time entry',
+    description: 'Correct a time entry - fix an over-tracked duration, edit its note, change its date, or re-target it to another ticket. Use THIS (not orboto_log_time) to fix a wrong entry: log_time is additive and only makes the total worse. Get the entryId from orboto_list_time_entries (or an orboto_log_time response). Blocked if the entry is locked by an approved timesheet.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3).describe('The ticket the entry currently belongs to.'),
+        entryId: z.string().uuid(),
+        durationMinutes: z.number().int().positive().optional(),
+        description: z.string().nullish(),
+        loggedAt: z.string().datetime().optional(),
+        moveToTicketKey: z.string().min(3).optional().describe('Re-target the entry to a different ticket.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeEditTimeEntryHandler(client) {
+    return async ({ ticketKey, entryId, durationMinutes, description, loggedAt, moveToTicketKey }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const body = {};
+        if (durationMinutes !== undefined)
+            body.durationMinutes = durationMinutes;
+        if (description !== undefined)
+            body.description = description;
+        if (loggedAt)
+            body.loggedAt = loggedAt;
+        if (moveToTicketKey) {
+            const dest = await resolveTicketByKey(client, moveToTicketKey);
+            body.ticketId = dest.id;
+        }
+        const updated = await client.patch(`/tickets/${ticket.id}/time-entries/${entryId}`, body);
+        return {
+            content: [{ type: 'text', text: `Updated time entry ${entryId.slice(0, 8)} on [${ticket.ticketKey}] → ${updated.durationMinutes} min.` }],
+            structuredContent: { ticketKey: ticket.ticketKey, entryId: updated.id, durationMinutes: updated.durationMinutes, ticketId: updated.ticketId },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_delete_time_entry  (ORB-1292)
+// ---------------------------------------------------------------------------
+export const deleteTimeEntryToolConfig = {
+    title: 'Delete a time entry',
+    description: 'Delete a time entry - e.g. a bogus over-tracked entry that should not exist at all (prefer orboto_edit_time_entry when it should just have a different duration). You can delete your own; deleting another user\'s needs the `time:delete_others` permission. Blocked if locked by an approved timesheet. Get the entryId from orboto_list_time_entries.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        entryId: z.string().uuid(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeDeleteTimeEntryHandler(client) {
+    return async ({ ticketKey, entryId }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        await client.delete(`/tickets/${ticket.id}/time-entries/${entryId}`);
+        return {
+            content: [{ type: 'text', text: `Deleted time entry ${entryId.slice(0, 8)} from [${ticket.ticketKey}].` }],
+            structuredContent: { ticketKey: ticket.ticketKey, entryId, deleted: true },
+        };
+    };
+}

package/dist/tools/time-writes.test.js

@@ -0,0 +1,138 @@
+/**
+ * ORB-244 Phase C Group 2 - time-tracking tool tests.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeTimerStartHandler, makeTimerStopHandler, makeLogTimeHandler, makeListTimeEntriesHandler, makeEditTimeEntryHandler, makeDeleteTimeEntryHandler, } from './time-writes.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        const u = url.toString();
+        const m = init?.method ?? 'GET';
+        const b = init?.body ? JSON.parse(init.body) : undefined;
+        calls.push({ url: u, method: m, body: b });
+        const r = responses.shift();
+        if (!r)
+            throw new Error(`unexpected extra fetch ${m} ${u}`);
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: 'OK',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => '',
+        };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const PROJ = { id: 'p1', key: 'ACME', name: 'Acme', description: null, status: 'active' };
+const TICKET = { id: 't1', projectId: 'p1', ticketKey: 'ACME-1', title: 'Bug' };
+describe('orboto_timer_start', () => {
+    it('starts with description + replace=false default', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: { id: 'tm1', ticketId: 't1', startedAt: 'now', accumulatedSeconds: 0, description: 'debug', pausedAt: null } },
+        ]);
+        await makeTimerStartHandler(client)({ ticketKey: 'ACME-1', description: 'debug' });
+        expect(calls[2].method).toBe('POST');
+        expect(calls[2].url).toContain('/time/timer/start');
+        expect(calls[2].body).toEqual({ ticketId: 't1', description: 'debug' });
+    });
+    it('passes replace=true when supplied', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: { id: 'tm1', ticketId: 't1', startedAt: 'now', accumulatedSeconds: 0, description: null, pausedAt: null } },
+        ]);
+        await makeTimerStartHandler(client)({ ticketKey: 'ACME-1', replace: true });
+        expect(calls[2].body).toEqual({ ticketId: 't1', replace: true });
+    });
+    it('rewrites a 409 into a clear message about replace=true', async () => {
+        stub([
+            { json: PROJ },
+            { json: TICKET },
+            { ok: false, status: 409, json: { error: 'Timer already running' } },
+        ]);
+        await expect(makeTimerStartHandler(client)({ ticketKey: 'ACME-1' })).rejects.toThrow(/replace=true/);
+    });
+});
+describe('orboto_timer_stop', () => {
+    it('returns durationMinutes from the API response', async () => {
+        const calls = stub([{ json: { durationMinutes: 47 } }]);
+        const res = await makeTimerStopHandler(client)();
+        expect(calls[0].method).toBe('POST');
+        expect(calls[0].url).toContain('/time/timer/stop');
+        expect(res.structuredContent).toEqual({ durationMinutes: 47 });
+        expect(res.content[0].text).toContain('47 min');
+    });
+    it('treats 404 as idempotent (no active timer)', async () => {
+        stub([{ ok: false, status: 404, json: { error: 'No active timer' } }]);
+        const res = await makeTimerStopHandler(client)();
+        const sc = res.structuredContent;
+        expect(sc.alreadyStopped).toBe(true);
+    });
+});
+describe('orboto_log_time', () => {
+    it('POSTs durationMinutes + optional description', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: { id: 'e1', ticketId: 't1', userId: 'u1', durationMinutes: 60, description: 'pair-debug', loggedAt: 'now' } },
+        ]);
+        await makeLogTimeHandler(client)({
+            ticketKey: 'ACME-1', durationMinutes: 60, description: 'pair-debug',
+        });
+        expect(calls[2].method).toBe('POST');
+        expect(calls[2].url).toContain('/tickets/t1/time-entries');
+        expect(calls[2].body).toEqual({ durationMinutes: 60, description: 'pair-debug' });
+    });
+    it('passes loggedAt for backdated entries', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: { id: 'e1', ticketId: 't1', userId: 'u1', durationMinutes: 30, description: null, loggedAt: '2026-04-20T10:00:00Z' } },
+        ]);
+        await makeLogTimeHandler(client)({
+            ticketKey: 'ACME-1', durationMinutes: 30, loggedAt: '2026-04-20T10:00:00Z',
+        });
+        expect(calls[2].body).toEqual({ durationMinutes: 30, loggedAt: '2026-04-20T10:00:00Z' });
+    });
+});
+describe('orboto_list_time_entries / edit / delete (ORB-1292)', () => {
+    it('list GETs the ticket time entries and returns them structured', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: { items: [{ id: 'e1', ticketId: 't1', userId: 'u1', durationMinutes: 476, loggedAt: 'now' }], nextCursor: null } },
+        ]);
+        const res = await makeListTimeEntriesHandler(client)({ ticketKey: 'ACME-1' });
+        expect(calls[2].method).toBe('GET');
+        expect(calls[2].url).toContain('/tickets/t1/time-entries');
+        expect(res.structuredContent.entries).toHaveLength(1);
+    });
+    it('edit PATCHes the entry by id with the new duration', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: { id: 'e1', ticketId: 't1', userId: 'u1', durationMinutes: 45, loggedAt: 'now' } },
+        ]);
+        await makeEditTimeEntryHandler(client)({ ticketKey: 'ACME-1', entryId: 'e1', durationMinutes: 45 });
+        expect(calls[2].method).toBe('PATCH');
+        expect(calls[2].url).toContain('/tickets/t1/time-entries/e1');
+        expect(calls[2].body).toEqual({ durationMinutes: 45 });
+    });
+    it('delete DELETEs the entry by id', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: {} },
+        ]);
+        const res = await makeDeleteTimeEntryHandler(client)({ ticketKey: 'ACME-1', entryId: 'e1' });
+        expect(calls[2].method).toBe('DELETE');
+        expect(calls[2].url).toContain('/tickets/t1/time-entries/e1');
+        expect(res.structuredContent.deleted).toBe(true);
+    });
+});

package/dist/tools/update-project.js

@@ -0,0 +1,165 @@
+/**
+ * ORB-885 - `orboto_update_project`.
+ * ORB-830 - `orboto_create_project` + `orboto_archive_project`.
+ *
+ * Project-CRUD write surface for the MCP. The read half
+ * (`orboto_list_projects`, `orboto_get_project`) shipped in ORB-244
+ * Phase B; ORB-885 added `update_project`, ORB-830 closes the gap
+ * with create + archive so an agent never has to drop to a raw
+ * `POST /projects` to spin up a new project.
+ *
+ * Status mutation is allowed in `update_project` (unlike
+ * `orboto_update_milestone`, which delegates closing to a dedicated
+ * tool) because project status is a four-state lifecycle (`draft` →
+ * `active` → `archived` / `closed`) with no extra semantics - a
+ * single patch field covers it cleanly. `archive_project` is a
+ * thin convenience over `update_project({ status: 'archived' })`
+ * because "archive this project" is a workflow agents reach for
+ * often enough that an explicit verb beats teaching the model the
+ * patch shape.
+ */
+import { z } from 'zod';
+import { resolveProjectByKey } from './shared.js';
+// Mirrors the Zod schema on `PATCH /projects/:id` (see
+// apps/api/src/routes/projects.ts). Kept in sync manually - there's no
+// generator from the API's runtime schema into the MCP package yet.
+const PROJECT_KEY_RE = /^[A-Z0-9]+$/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// ORB-993/ORB-994 - the 18 detector-supported workspace/project locales.
+// Mirrors WORKSPACE_LOCALE_CODES in @orboto/shared-schema (kept in sync
+// manually, same as the rest of this tool's schema).
+const LOCALE_CODES = ['en', 'de', 'fr', 'es', 'it', 'nl', 'pt', 'ru', 'pl', 'tr', 'cs', 'da', 'sv', 'no', 'fi', 'ja', 'zh', 'ko'];
+export const updateProjectToolConfig = {
+    title: 'Update a project\'s metadata',
+    description: 'Patch a project (`name`, `description`, `key`, `status`, `branchTemplate`, `customerId`, `language`). At least one field must be set. Use `status: "archived"` or `"closed"` to take a project out of active rotation. Renaming the `key` also rewrites every ticket\'s `PROJ-N` reference - handle with care. `language` sets the project\'s expected ticket language (one of the 18 supported locales); pass null to inherit the workspace language.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Current project key (e.g. "ACME"). Case-insensitive.'),
+        patch: z.object({
+            name: z.string().min(1).max(255).optional(),
+            description: z.string().nullable().optional().describe('Pass null to clear the description.'),
+            key: z.string().min(2).max(10).regex(PROJECT_KEY_RE).optional()
+                .describe('New project key. A-Z0-9 only, 2-10 chars. Rewrites every ticket reference.'),
+            status: z.enum(['draft', 'active', 'archived', 'closed']).optional(),
+            branchTemplate: z.string().max(100).nullable().optional(),
+            customerId: z.string().regex(UUID_RE).nullable().optional()
+                .describe('UUID of a customer record, or null to detach.'),
+            language: z.enum(LOCALE_CODES).nullable().optional()
+                .describe('Project content language (ORB-994). Wins over the workspace language for this project. null = inherit workspace.'),
+        }).refine((p) => Object.keys(p).length > 0, { message: 'patch must include at least one field' }),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeUpdateProjectHandler(client) {
+    return async ({ projectKey, patch }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        const updated = await client.patch(`/projects/${project.id}`, patch);
+        const fields = Object.keys(patch).join(', ');
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Updated project ${updated.key} - ${updated.name} (${fields}).`,
+                }],
+            structuredContent: {
+                id: updated.id,
+                key: updated.key,
+                name: updated.name,
+                description: updated.description,
+                status: updated.status,
+                language: updated.language ?? null,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_create_project - ORB-830
+// ---------------------------------------------------------------------------
+export const createProjectToolConfig = {
+    title: 'Create a new project',
+    description: 'Create a new project in the workspace. `name` is required; `key` is optional and the API auto-derives one from the name when omitted (uppercase initials). Returns the new project\'s id + key + status (`active` by default). Caller must have `admin:project:create` or be a super-admin. Note: a new project is auto-provisioned with a general doc space (slug `<key>-general`, system-generated, for the AI primer + notes) - don\'t create a separate doc space for its docs, reuse that one (orboto_list_doc_spaces).',
+    inputSchema: z.object({
+        name: z.string().min(1).max(255).describe('Display name for the project.'),
+        key: z.string().min(2).max(10).regex(PROJECT_KEY_RE).optional()
+            .describe('Optional explicit key (e.g. "ACME"). A-Z0-9 only, 2-10 chars. Auto-derived from name when omitted.'),
+        description: z.string().nullable().optional().describe('Optional free-text description.'),
+        customerId: z.string().regex(UUID_RE).nullable().optional()
+            .describe('Optional UUID of a customer record to attach the project to.'),
+        language: z.enum(LOCALE_CODES).nullable().optional()
+            .describe('Optional project content language (ORB-994), one of the 18 supported locales. Omit/null = inherit the workspace language.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeCreateProjectHandler(client) {
+    return async ({ name, key, description, customerId, language }) => {
+        const body = { name };
+        if (key !== undefined)
+            body.key = key;
+        if (description !== undefined)
+            body.description = description;
+        if (customerId !== undefined)
+            body.customerId = customerId;
+        if (language !== undefined)
+            body.language = language;
+        const created = await client.post('/projects', body);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Created project ${created.key} - ${created.name} (status: ${created.status}).`,
+                }],
+            structuredContent: {
+                id: created.id,
+                key: created.key,
+                name: created.name,
+                description: created.description,
+                status: created.status,
+                language: created.language ?? null,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_archive_project - ORB-830
+// ---------------------------------------------------------------------------
+export const archiveProjectToolConfig = {
+    title: 'Archive a project',
+    description: 'Archive a project - moves it out of the active rotation without deleting any data. Convenience wrapper around `orboto_update_project({ status: "archived" })` because "archive this project" is a workflow operators hit often. Archiving is reversible: pass the same project back through `orboto_update_project({ status: "active" })` to restore. Idempotent - re-archiving an already-archived project is a no-op success.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key (e.g. "ACME") of the project to archive.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeArchiveProjectHandler(client) {
+    return async ({ projectKey }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        if (project.status === 'archived') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Project ${project.key} is already archived (no-op).`,
+                    }],
+                structuredContent: {
+                    id: project.id,
+                    key: project.key,
+                    name: project.name,
+                    description: project.description,
+                    status: project.status,
+                    alreadyArchived: true,
+                },
+            };
+        }
+        const updated = await client.patch(`/projects/${project.id}`, { status: 'archived' });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Archived project ${updated.key} - ${updated.name}.`,
+                }],
+            structuredContent: {
+                id: updated.id,
+                key: updated.key,
+                name: updated.name,
+                description: updated.description,
+                status: updated.status,
+                alreadyArchived: false,
+            },
+        };
+    };
+}