@loicngr/kobo 2.1.15 → 2.1.18

package/dist/shared/pr-checkout-steps.js

@@ -0,0 +1,86 @@
+/** Blockers the user CAN resolve, by picking another worktree path. Everything
+ *  else (missing CLI, fork PR, deleted remote branch, index.lock, unrelated
+ *  history) leaves nothing to choose and ends the flow. */
+const RESOLVABLE_BLOCKERS = new Set(['path-occupied', 'worktree-other-branch']);
+/**
+ * Derive the ordered steps for a report. A blocker short-circuits everything:
+ * there is no point asking about a stash when the forge CLI is missing.
+ * `operation` precedes `changes` because aborting a rebase changes what is dirty.
+ */
+export function deriveSteps(report) {
+    const fatal = report.blockers.filter((b) => !RESOLVABLE_BLOCKERS.has(b.kind));
+    if (fatal.length > 0) {
+        return [{ id: 'blocked', blocking: true, titleKey: 'prCheckout.step.blocked' }];
+    }
+    const steps = [];
+    if (report.blockers.some((b) => RESOLVABLE_BLOCKERS.has(b.kind))) {
+        steps.push({ id: 'path', blocking: false, titleKey: 'prCheckout.step.path' });
+    }
+    if (report.workspace.state !== 'none') {
+        steps.push({ id: 'workspace', blocking: false, titleKey: 'prCheckout.step.workspace' });
+    }
+    // A purged workspace's worktree can reappear as an 'orphan' on disk during the
+    // pr-watcher's restore window (see AGENTS.md § Worktree purge) — restoring the
+    // workspace (via the 'workspace' step above) already handles reattaching it, so
+    // this must not also surface as a separate worktree step.
+    if (report.workspace.state !== 'purged' &&
+        (report.worktree.state === 'orphan' || report.worktree.state === 'attached')) {
+        steps.push({ id: 'worktree', blocking: false, titleKey: 'prCheckout.step.worktree' });
+    }
+    if (report.ongoingOperation) {
+        steps.push({ id: 'operation', blocking: false, titleKey: 'prCheckout.step.operation' });
+    }
+    if (report.localChanges.present) {
+        steps.push({ id: 'changes', blocking: false, titleKey: 'prCheckout.step.changes' });
+    }
+    if (report.branch.state === 'behind' || report.branch.state === 'ahead' || report.branch.state === 'diverged') {
+        steps.push({ id: 'divergence', blocking: false, titleKey: 'prCheckout.step.divergence' });
+    }
+    return steps;
+}
+/**
+ * The pre-selected choice for each step. The rule that matters: wherever local
+ * commits or local edits exist, the default is the one that loses nothing.
+ */
+export function defaultDecisions(report) {
+    const decisions = {};
+    if (report.workspace.state === 'active')
+        decisions.existingWorkspace = 'open';
+    if (report.workspace.state === 'archived')
+        decisions.archivedWorkspace = 'unarchive';
+    if (report.workspace.state === 'purged')
+        decisions.purgedWorktree = 'restore';
+    // A purged workspace's worktree can reappear as an 'orphan' on disk during the
+    // pr-watcher's restore window (see AGENTS.md § Worktree purge) — restoring the
+    // workspace already handles reattaching it, so this must not also surface as a
+    // separate 'attach' decision.
+    if (report.workspace.state !== 'purged' && report.worktree.state === 'orphan')
+        decisions.orphanWorktree = 'attach';
+    // 'cancel' — not 'abort' — is the loses-nothing default: aborting a rebase
+    // or merge discards any conflict-resolution work already staged, exactly
+    // the kind of destructive default this function otherwise avoids.
+    if (report.ongoingOperation)
+        decisions.ongoingOperation = 'cancel';
+    if (report.localChanges.present)
+        decisions.localChanges = 'keep';
+    if (report.branch.state === 'behind')
+        decisions.divergence = 'fast-forward';
+    else if (report.branch.state === 'ahead' || report.branch.state === 'diverged')
+        decisions.divergence = 'keep';
+    return decisions;
+}
+/** Return an i18n key for choices that cannot preserve the requested work. */
+export function checkoutDecisionError(report, decisions) {
+    if (decisions.divergence === 'fast-forward' &&
+        (report.branch.state === 'ahead' || report.branch.state === 'diverged'))
+        return 'prCheckout.divergence.notFastForward';
+    if ((report.worktree.state === 'orphan' || report.worktree.state === 'attached') &&
+        decisions.orphanWorktree === 'create-elsewhere')
+        return 'prCheckout.worktree.branchInUse';
+    if (report.localChanges.present &&
+        (decisions.localChanges ?? 'keep') === 'keep' &&
+        decisions.divergence === 'reset-hard') {
+        return 'prCheckout.changes.keepResetConflict';
+    }
+    return null;
+}

package/dist/shared/workspace-creation-tools.js

@@ -0,0 +1,182 @@
+import { MAX_ATTACHMENTS, MAX_ATTACHMENTS_BYTES, validateAttachments } from './attachments.js';
+/** Base64 expansion of the shared upload limit, plus bounded JSON metadata. */
+export const MAX_MCP_CREATION_REQUEST_BYTES = Math.ceil(MAX_ATTACHMENTS_BYTES / 3) * 4 + 1024 * 1024;
+const string = (maxLength = 200, minLength = 1) => ({ type: 'string', minLength, maxLength });
+const choice = (...values) => ({ type: 'string', enum: values });
+const object = (properties, required = []) => ({
+    type: 'object',
+    properties,
+    required,
+    additionalProperties: false,
+});
+const effort = choice('auto', 'none', 'low', 'medium', 'high', 'xhigh', 'max');
+const engine = choice('claude-code', 'codex');
+const path = string(4096);
+const url = string(4096);
+const titles = { type: 'array', items: string(20_000), maxItems: 500 };
+const properties = {
+    name: string(1000),
+    project_path: path,
+    source_branch: string(1024),
+    working_branch: string(1024),
+    engine,
+    model: string(),
+    reasoning_effort: effort,
+    brainstorm_model: string(),
+    brainstorm_reasoning_effort: effort,
+    description: string(200_000, 0),
+    tags: { type: 'array', items: string(200), maxItems: 100 },
+    tasks: titles,
+    acceptance_criteria: titles,
+    agent_permission_mode: choice('plan', 'bypass', 'strict', 'interactive'),
+    auto_loop: { type: 'boolean' },
+    auto_loop_session_mode: choice('per_task', 'continuous'),
+    skip_setup_script: { type: 'boolean' },
+    auto_loop_final_review: {
+        ...object({ engine, model: string(), reasoning_effort: effort, additional_instructions: string(20_000, 0) }, [
+            'engine',
+            'model',
+            'reasoning_effort',
+        ]),
+        type: ['object', 'null'],
+    },
+    workflow_policy: object({
+        commit: choice('manual', 'automatic'),
+        push: choice('manual', 'automatic'),
+        publish: choice('manual', 'automatic'),
+    }),
+    notion_url: {
+        ...url,
+        description: 'Import this Notion ticket before launching the agent. Requires an enabled, configured Notion integration.',
+    },
+    notion_page_id: {
+        ...string(),
+        description: 'Optional stored Notion page identifier. Does not import content on its own; provide notion_url to import the ticket.',
+    },
+    sentry_url: url,
+    pr_url: url,
+    worktree_path: path,
+    comparison_id: string(),
+    creation_id: string(),
+    attachments: {
+        type: 'array',
+        maxItems: MAX_ATTACHMENTS,
+        items: object({ name: string(255), mime_type: string(200, 0), data_base64: string(Math.ceil(MAX_ATTACHMENTS_BYTES / 3) * 4) }, ['name', 'mime_type', 'data_base64']),
+    },
+    pr_checkout: object({
+        fingerprint: string(),
+        decisions: object({
+            existingWorkspace: choice('open', 'continue'),
+            archivedWorkspace: choice('unarchive', 'continue'),
+            purgedWorktree: choice('restore'),
+            orphanWorktree: choice('attach', 'create-elsewhere'),
+            pathCollision: object({ worktreePath: path }, ['worktreePath']),
+            localChanges: choice('stash', 'commit', 'discard', 'keep'),
+            ongoingOperation: choice('abort', 'cancel'),
+            divergence: choice('fast-forward', 'rebase', 'reset-hard', 'keep'),
+        }),
+    }, ['fingerprint', 'decisions']),
+};
+const schemas = {
+    create_workspace: object(properties, ['name', 'project_path']),
+    diagnose_workspace_pr: object({ project_path: path, pr_url: url }, ['project_path', 'pr_url']),
+};
+export const WORKSPACE_CREATION_TOOLS = [
+    {
+        name: 'create_workspace',
+        description: 'Create a Kōbō workspace with the same configuration as the create form, including final review, workflow policy, imports and inline base64 attachments (10 files, 50 MiB total). Plain creation requires source_branch and working_branch; worktree_path requires source_branch. A pr_url derives canonical branches and diagnoses checkout first. Unsafe or ambiguous checkout returns requiresAction and a fingerprint: repeat with explicit pr_checkout decisions. Never silently discards local work. Existing workspaces can be opened or explicitly unarchived; no duplicate is created. skip_setup_script defaults to true for PR checkout. Project must be configured in Kōbō.',
+        inputSchema: schemas.create_workspace,
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    },
+    {
+        name: 'diagnose_workspace_pr',
+        description: 'Read the canonical PR and local checkout state for a configured project. Returns report, pr and fingerprint for explicit create_workspace pr_checkout decisions; creates no workspace and applies no checkout changes.',
+        inputSchema: schemas.diagnose_workspace_pr,
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    },
+];
+export function isWorkspaceCreationTool(name) {
+    return Object.hasOwn(schemas, name);
+}
+function validate(schema, value, label) {
+    if (value === null && Array.isArray(schema.type))
+        return;
+    if (schema.type === 'object' || Array.isArray(schema.type)) {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error(`${label} must be an object`);
+        const input = value;
+        for (const key of Object.keys(input)) {
+            if (!Object.hasOwn(schema.properties, key))
+                throw new Error(`Unknown field ${label}.${key}`);
+            validate(schema.properties[key], input[key], `${label}.${key}`);
+        }
+        for (const key of schema.required ?? [])
+            if (!Object.hasOwn(input, key))
+                throw new Error(`${label}.${key} is required`);
+    }
+    else if (schema.type === 'array') {
+        if (!Array.isArray(value) || value.length > schema.maxItems)
+            throw new Error(`${label} must be an array with at most ${schema.maxItems} entries`);
+        for (const item of value)
+            validate(schema.items, item, label);
+    }
+    else if (schema.type === 'boolean') {
+        if (typeof value !== 'boolean')
+            throw new Error(`${label} must be a boolean`);
+    }
+    else {
+        if (typeof value !== 'string' ||
+            value.includes('\0') ||
+            value.length < (schema.minLength ?? 0) ||
+            value.length > (schema.maxLength ?? Infinity) ||
+            (schema.minLength && !value.trim()) ||
+            (schema.enum && !schema.enum.includes(value)))
+            throw new Error(`Invalid ${label}`);
+    }
+}
+/** Validates before dispatch, including uploads before a PR checkout can mutate Git. */
+export function validateWorkspaceCreationArguments(name, input) {
+    if (!isWorkspaceCreationTool(name))
+        throw new Error(`Unknown workspace creation tool: ${name}`);
+    validate(schemas[name], input, name);
+    const value = input;
+    for (const key of ['notion_url', 'sentry_url', 'pr_url']) {
+        if (value[key] !== undefined) {
+            const parsed = new URL(value[key]);
+            if (!['https:', 'http:'].includes(parsed.protocol) || parsed.username || parsed.password)
+                throw new Error(`Invalid ${key}`);
+        }
+    }
+    if (name === 'create_workspace') {
+        const { attachments: _attachments, ...metadataFields } = value;
+        // Keep room for multipart file headers within the downstream 1 MiB allowance.
+        if (new TextEncoder().encode(JSON.stringify(metadataFields)).byteLength > 960 * 1024)
+            throw new Error('Workspace creation metadata exceeds 960 KiB');
+        if (!value.pr_url && (!value.source_branch || (!value.worktree_path && !value.working_branch)))
+            throw new Error('source_branch and working_branch are required unless using a PR or existing worktree');
+        if (value.pr_checkout && !value.pr_url)
+            throw new Error('pr_checkout requires pr_url');
+        const files = (value.attachments ?? []);
+        const metadata = files.map((file) => {
+            if (/[/\\]/.test(file.name) || file.name === '.' || file.name === '..')
+                throw new Error('Attachment name must be a filename, not a path');
+            const data = file.data_base64;
+            if (data.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(data))
+                throw new Error('Attachment data_base64 must be canonical base64');
+            // Reject non-zero pad bits too, before the server allocates decoded buffers.
+            const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+            if ((data.endsWith('==') && (alphabet.indexOf(data.at(-3)) & 15) !== 0) ||
+                (!data.endsWith('==') && data.endsWith('=') && (alphabet.indexOf(data.at(-2)) & 3) !== 0))
+                throw new Error('Attachment data_base64 must be canonical base64');
+            return {
+                name: file.name,
+                type: file.mime_type,
+                size: (data.length / 4) * 3 - (data.endsWith('==') ? 2 : data.endsWith('=') ? 1 : 0),
+            };
+        });
+        const error = validateAttachments(metadata);
+        if (error)
+            throw new Error(`Invalid attachments: ${error}`);
+    }
+    return value;
+}

package/dist/shared/workspace-group-message-tools.js

@@ -0,0 +1,134 @@
+import { MAX_GROUP_MESSAGE_LENGTH, MAX_GROUP_MESSAGE_RECIPIENTS, parseGroupMessageInput, } from './workspace-group-messages.js';
+const identifier = { type: 'string', pattern: '^[A-Za-z0-9_-]{1,200}$', minLength: 1, maxLength: 200 };
+const statuses = [
+    'created',
+    'extracting',
+    'brainstorming',
+    'executing',
+    'compacting',
+    'awaiting-user',
+    'completed',
+    'idle',
+    'error',
+    'quota',
+];
+export const WORKSPACE_GROUP_MESSAGE_TOOLS = [
+    {
+        name: 'preview_workspace_group_message',
+        description: 'Preview eligible non-archived, non-purged workspaces before sending a group message. Tags match ANY selected tag, statuses match ANY selected status, and all enabled filters intersect. Set dev_server_running to true to include only workspaces with a running development server. Empty filters select all eligible workspaces. Paginate with offset and limit (maximum 200); results sort by workspace ID. Delivery is immediate for manual workspaces and next_iteration for auto-loop. This is a live preview, not a reservation; explicitly select recipient IDs for send_workspace_group_message.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tags: {
+                    type: 'array',
+                    maxItems: 200,
+                    uniqueItems: true,
+                    items: { type: 'string', minLength: 1, maxLength: 200 },
+                },
+                statuses: {
+                    type: 'array',
+                    uniqueItems: true,
+                    maxItems: statuses.length,
+                    items: { type: 'string', enum: statuses },
+                },
+                dev_server_running: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'Only include workspaces whose development server status is running. Intersects other filters.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: MAX_GROUP_MESSAGE_RECIPIENTS,
+                    default: MAX_GROUP_MESSAGE_RECIPIENTS,
+                },
+                offset: { type: 'integer', minimum: 0, default: 0 },
+            },
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: 'send_workspace_group_message',
+        description: 'Send one message to an explicit selection of 1–200 unique workspace IDs after previewing recipients. A workspace-bound agent cannot target its own workspace. Supply a unique request_id; retrying the same ID and identical payload observes the existing batch without resending. Different payloads with that ID fail. Returns a durable asynchronous batch receipt: use get_workspace_group_message to inspect per-recipient outcomes. Manual workspaces receive immediately; auto-loop workspaces queue for their next iteration. Ineligible targets are rejected individually. After interruption, not_sent and unknown outcomes are never automatically retried; inspect history before submitting a new request.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                request_id: identifier,
+                workspace_ids: {
+                    type: 'array',
+                    minItems: 1,
+                    maxItems: MAX_GROUP_MESSAGE_RECIPIENTS,
+                    uniqueItems: true,
+                    items: identifier,
+                },
+                content: { type: 'string', minLength: 1, maxLength: MAX_GROUP_MESSAGE_LENGTH },
+            },
+            required: ['request_id', 'workspace_ids', 'content'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
+    {
+        name: 'get_workspace_group_message',
+        description: 'Read a persisted group-message receipt by request_id, including complete and each recipient state: pending, sending, sent, queued, rejected, unknown, or not_sent. This read never sends or retries messages. Queued means accepted for a future auto-loop iteration, not executed.',
+        inputSchema: {
+            type: 'object',
+            properties: { request_id: identifier },
+            required: ['request_id'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+];
+export function isWorkspaceGroupMessageTool(name) {
+    return WORKSPACE_GROUP_MESSAGE_TOOLS.some((tool) => tool.name === name);
+}
+export function validateWorkspaceGroupMessageArguments(name, raw) {
+    const tool = WORKSPACE_GROUP_MESSAGE_TOOLS.find((item) => item.name === name);
+    if (!tool)
+        throw new Error(`Unknown group message tool: ${name}`);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        throw new Error('Arguments must be an object');
+    const input = raw;
+    for (const key of Object.keys(input))
+        if (!Object.hasOwn(tool.inputSchema.properties, key))
+            throw new Error(`Unknown field: ${key}`);
+    for (const key of tool.inputSchema.required ?? [])
+        if (!Object.hasOwn(input, key))
+            throw new Error(`${key} is required`);
+    if (name === 'send_workspace_group_message') {
+        parseGroupMessageInput({ requestId: input.request_id, workspaceIds: input.workspace_ids, content: input.content });
+    }
+    else if (name === 'get_workspace_group_message') {
+        if (typeof input.request_id !== 'string' || !/^[A-Za-z0-9_-]{1,200}$/.test(input.request_id))
+            throw new Error('Invalid request_id');
+    }
+    else {
+        if (input.dev_server_running !== undefined && typeof input.dev_server_running !== 'boolean')
+            throw new Error('Invalid dev_server_running');
+        for (const key of ['tags', 'statuses']) {
+            const value = input[key];
+            if (value === undefined)
+                continue;
+            if (!Array.isArray(value) ||
+                value.length > (key === 'tags' ? 200 : statuses.length) ||
+                new Set(value).size !== value.length ||
+                value.some((item) => typeof item !== 'string' ||
+                    !item.trim() ||
+                    item.length > 200 ||
+                    (key === 'statuses' && !statuses.includes(item))))
+                throw new Error(`Invalid ${key}`);
+        }
+        if (input.limit !== undefined &&
+            (typeof input.limit !== 'number' ||
+                !Number.isSafeInteger(input.limit) ||
+                input.limit < 1 ||
+                input.limit > MAX_GROUP_MESSAGE_RECIPIENTS))
+            throw new Error('Invalid limit');
+        if (input.offset !== undefined &&
+            (typeof input.offset !== 'number' || !Number.isSafeInteger(input.offset) || input.offset < 0))
+            throw new Error('Invalid offset');
+    }
+    return input;
+}

package/dist/shared/workspace-group-messages.js

@@ -0,0 +1,27 @@
+export const MAX_GROUP_MESSAGE_RECIPIENTS = 200;
+export const MAX_GROUP_MESSAGE_LENGTH = 100_000;
+export const MAX_GROUP_MESSAGE_REQUEST_BYTES = 1024 * 1024;
+const identifier = /^[A-Za-z0-9_-]{1,200}$/;
+export function parseGroupMessageInput(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid group message');
+    const input = value;
+    if (Object.keys(input).some((key) => !['requestId', 'workspaceIds', 'content'].includes(key)))
+        throw new Error('Unknown group message field');
+    if (typeof input.requestId !== 'string' || !identifier.test(input.requestId))
+        throw new Error('Invalid requestId');
+    if (!Array.isArray(input.workspaceIds) ||
+        input.workspaceIds.length === 0 ||
+        input.workspaceIds.length > MAX_GROUP_MESSAGE_RECIPIENTS ||
+        input.workspaceIds.some((id) => typeof id !== 'string' || !identifier.test(id)) ||
+        new Set(input.workspaceIds).size !== input.workspaceIds.length)
+        throw new Error('Select 1 to 200 unique workspace IDs');
+    if (typeof input.content !== 'string' || !input.content.trim() || input.content.length > MAX_GROUP_MESSAGE_LENGTH)
+        throw new Error('Message must contain 1 to 100000 characters');
+    return { requestId: input.requestId, workspaceIds: [...input.workspaceIds], content: input.content };
+}
+export function matchesGroupMessageFilters(workspace, filters) {
+    return ((!filters.tags?.length || filters.tags.some((tag) => workspace.tags.includes(tag))) &&
+        (!filters.statuses?.length || filters.statuses.includes(workspace.status)) &&
+        (!filters.devServerRunning || workspace.devServerStatus === 'running'));
+}

package/dist/shared/workspace-lifecycle-tools.js

@@ -0,0 +1,112 @@
+const workspaceId = {
+    type: 'string',
+    minLength: 1,
+    maxLength: 200,
+    pattern: '^[A-Za-z0-9_-]+$',
+    description: 'Exact workspace ID from list_workspaces. The reserved bulk endpoint name archived is forbidden.',
+};
+const branch = {
+    type: 'string',
+    minLength: 1,
+    maxLength: 1024,
+    description: 'Current exact working branch name, from get_workspace. Required for every deletion, like the UI confirmation.',
+};
+export const WORKSPACE_LIFECYCLE_TOOLS = [
+    {
+        name: 'archive_workspace',
+        description: 'Archive a Kōbō workspace using the same lifecycle as the UI. Stops its agent, development server and terminal, disables auto-loop, and hides the workspace while retaining its checkout and conversation history. May run the configured archive script.',
+        inputSchema: {
+            type: 'object',
+            properties: { workspace_id: workspaceId },
+            required: ['workspace_id'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    {
+        name: 'purge_workspace_worktree',
+        description: 'Free disk space by removing a Kōbō-owned workspace checkout, stopping its processes and archiving it, while preserving conversation history and workspace metadata. Uncommitted files in the checkout can be lost. External attached worktrees are protected. Set confirm_purge=true to explicitly request removal. Inspect the returned outcome and warnings; removal-failed is not success.',
+        inputSchema: {
+            type: 'object',
+            properties: { workspace_id: workspaceId, confirm_purge: { type: 'boolean', const: true } },
+            required: ['workspace_id', 'confirm_purge'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    },
+    {
+        name: 'delete_workspace',
+        description: 'Permanently delete one Kōbō workspace, its tasks and conversation history and its owned checkout, using the UI lifecycle. Stops processes first; external attached worktrees are preserved. Requires confirm_delete=true and confirmation_branch matching the current working branch. Local and remote branch deletion default to false and require explicit flags; remote deletion also requires delete_local_branch=true. Cleanup warnings are returned and must not be treated as complete cleanup. Never deletes all archived workspaces.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspace_id: workspaceId,
+                confirm_delete: { type: 'boolean', const: true },
+                confirmation_branch: branch,
+                delete_local_branch: { type: 'boolean', default: false },
+                delete_remote_branch: { type: 'boolean', default: false },
+            },
+            required: ['workspace_id', 'confirm_delete', 'confirmation_branch'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    },
+    {
+        name: 'unarchive_workspace',
+        description: 'Unarchive a Kōbō workspace whose checkout is still available, preserving its prior status and conversation history. Does not start agents or setup scripts. A purged checkout is refused: use restore_workspace first.',
+        inputSchema: {
+            type: 'object',
+            properties: { workspace_id: workspaceId },
+            required: ['workspace_id'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    },
+    {
+        name: 'restore_workspace',
+        description: 'Restore an archived workspace, recreating its Kōbō-owned checkout when marked purged, then unarchiving it. Uses saved Git recovery metadata, preserves history and never starts agents or setup scripts. An already active unpurged workspace is unchanged. Missing checkout without purge metadata is refused (not-purged); a workspace permanently deleted from the database cannot be restored. External worktrees are only unarchived, never recreated. Return includes workspace and outcome, plus checkout source when restoration was needed.',
+        inputSchema: {
+            type: 'object',
+            properties: { workspace_id: workspaceId },
+            required: ['workspace_id'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+];
+export function isWorkspaceLifecycleTool(name) {
+    return WORKSPACE_LIFECYCLE_TOOLS.some((tool) => tool.name === name);
+}
+/** Reject ambiguous or bulk targets before any dispatch, including a read. */
+export function validateWorkspaceLifecycleArguments(name, raw) {
+    const tool = WORKSPACE_LIFECYCLE_TOOLS.find((definition) => definition.name === name);
+    if (!tool)
+        throw new Error(`Unknown workspace lifecycle tool: ${name}`);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        throw new Error('Tool arguments must be an object');
+    const input = raw;
+    const properties = tool.inputSchema.properties;
+    for (const required of tool.inputSchema.required ?? [])
+        if (!Object.hasOwn(input, required))
+            throw new Error(`${required} is required`);
+    for (const [key, value] of Object.entries(input)) {
+        if (!Object.hasOwn(properties, key))
+            throw new Error(`Unknown field: ${key}`);
+        const definition = properties[key];
+        if (definition.type === 'boolean') {
+            if (typeof value !== 'boolean' || (definition.const !== undefined && value !== definition.const))
+                throw new Error(`${key} must be ${definition.const === true ? 'true' : 'a boolean'}`);
+        }
+        else if (typeof value !== 'string' ||
+            !value.trim() ||
+            value.length > definition.maxLength ||
+            /[\0\r\n]/.test(value))
+            throw new Error(`Invalid ${key}`);
+    }
+    const id = input.workspace_id;
+    if (!/^[A-Za-z0-9_-]+$/.test(id) || id === 'archived')
+        throw new Error('Invalid workspace_id: use a single workspace ID, never a path or bulk endpoint');
+    if (input.delete_remote_branch === true && input.delete_local_branch !== true)
+        throw new Error('delete_remote_branch requires delete_local_branch=true');
+    return input;
+}

package/docker-compose.vps.yml

@@ -0,0 +1,60 @@
+# Fresh, independent Kōbō instance behind an EXISTING Traefik Docker provider.
+# Setup, authentication and upgrades: docs/deployment-vps.md
+# Copy to your deployment directory as compose.yaml and create its .env first.
+name: kobo
+
+services:
+  kobo:
+    # Build this initial image locally. kobo-update later pins a unique release tag.
+    image: kobo:local
+    init: true
+    restart: unless-stopped
+    # Use the host's SSH and `docker compose exec`; no container SSH daemon.
+    entrypoint: ["node"]
+    command: ["dist/server/index.js"]
+    environment:
+      NODE_ENV: production
+      SERVER_PORT: "3000"
+      KOBO_HOME: /root/.config/kobo
+      KOBO_NETWORK_ACCESS_ENABLED: "true"
+      KOBO_NETWORK_ACCESS_BEHIND_PROXY: "true"
+      KOBO_NETWORK_ACCESS_PROXY_HOST: ${KOBO_DOMAIN:?Set KOBO_DOMAIN to the public hostname}
+    volumes:
+      # Includes Kōbō, Claude/Codex state and Git configuration; no PC auth mounts.
+      - kobo-home:/root
+      # Same ABSOLUTE path in both namespaces for project Docker bind mounts.
+      # Create the host directory first; fail rather than silently making one.
+      - type: bind
+        source: ${KOBO_PROJECTS_DIR:?Set KOBO_PROJECTS_DIR to an existing absolute path}
+        target: ${KOBO_PROJECTS_DIR:?Set KOBO_PROJECTS_DIR to an existing absolute path}
+        bind:
+          create_host_path: false
+      # Optional: enables project Docker commands, with root-equivalent host access.
+      # - /var/run/docker.sock:/var/run/docker.sock
+    networks:
+      - proxy
+    labels:
+      traefik.enable: "true"
+      traefik.docker.network: ${TRAEFIK_NETWORK:-web}
+      traefik.http.routers.kobo.rule: Host(`${KOBO_DOMAIN:?Set KOBO_DOMAIN to the public hostname}`)
+      traefik.http.routers.kobo.entrypoints: ${TRAEFIK_ENTRYPOINT:-websecure}
+      traefik.http.routers.kobo.tls: "true"
+      traefik.http.routers.kobo.tls.certresolver: ${TRAEFIK_CERTRESOLVER:-letsencrypt}
+      traefik.http.services.kobo.loadbalancer.server.port: "3000"
+    # No published HTTP or SSH ports. Traefik handles HTTP and WebSockets.
+    stop_grace_period: 60s
+    healthcheck:
+      start_period: 60s
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+        max-file: "3"
+
+networks:
+  proxy:
+    external: true
+    name: ${TRAEFIK_NETWORK:-web}
+
+volumes:
+  kobo-home: