@orboto/mcp 0.178.0

package/dist/tools/get-checklists.js

@@ -0,0 +1,72 @@
+/**
+ * ORB-244 Phase B - `orboto_get_checklists`.
+ *
+ * Dedicated read tool for a ticket's checklists. Two callers want
+ * this without paying for the full ticket payload:
+ *
+ *   1. Models asking "what's still unchecked on ACME-42?" - don't
+ *      need description + comments + git activity for that.
+ *   2. Phase-C write tools (`orboto_check` / `orboto_uncheck`) - the
+ *      user usually wants to confirm the item exists before
+ *      toggling it, and this tool is the cheap round-trip.
+ *
+ * ORB-234 detail exposed here: when a checklist item links to
+ * another ticket, `effectiveCompleted` mirrors that ticket's status
+ * category. We surface the linked ticket so the model can explain
+ * "item is done because [ORB-99] shipped" rather than just "done".
+ */
+import { z } from 'zod';
+import { resolveTicketByKey } from './shared.js';
+export const getChecklistsToolConfig = {
+    title: 'Get ticket checklists',
+    description: 'Return all checklists on a ticket with per-item completion state. Items that link to another ticket carry that ticket\'s key + status so the model can explain why an item is (not) done.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3).describe('Ticket key like "ACME-42".'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeGetChecklistsHandler(client) {
+    return async ({ ticketKey }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const checklists = await client.get(`/tickets/${ticket.id}/checklists`);
+        if (checklists.length === 0) {
+            return {
+                content: [{ type: 'text', text: `[${ticket.ticketKey}] has no checklists.` }],
+                structuredContent: { ticketKey: ticket.ticketKey, checklists: [] },
+            };
+        }
+        const lines = [];
+        for (const cl of checklists) {
+            lines.push(`### ${cl.title} (${cl.progress.done}/${cl.progress.total})${cl.triggersDone ? ' · triggers ticket done' : ''}`);
+            for (const i of cl.items) {
+                const linkSuffix = i.linkedTicketKey
+                    ? ` ↪ [${i.linkedTicketKey}] ${i.linkedTicketTitle ?? ''} (${i.linkedTicketStatusCategory ?? 'unknown'})`
+                    : '';
+                lines.push(`- [${i.effectiveCompleted ? 'x' : ' '}] ${i.content}${linkSuffix}`);
+            }
+            lines.push('');
+        }
+        return {
+            content: [{ type: 'text', text: lines.join('\n').trimEnd() }],
+            structuredContent: {
+                ticketKey: ticket.ticketKey,
+                checklists: checklists.map((cl) => ({
+                    id: cl.id,
+                    title: cl.title,
+                    triggersDone: cl.triggersDone,
+                    progress: cl.progress,
+                    items: cl.items.map((i) => ({
+                        id: i.id,
+                        content: i.content,
+                        done: i.effectiveCompleted,
+                        linkedTicket: i.linkedTicketKey ? {
+                            key: i.linkedTicketKey,
+                            title: i.linkedTicketTitle,
+                            statusCategory: i.linkedTicketStatusCategory,
+                        } : null,
+                    })),
+                })),
+            },
+        };
+    };
+}

package/dist/tools/get-project-primer.js

@@ -0,0 +1,58 @@
+/**
+ * ORB-408 (Phase 3 of ORB-406) - `orboto_get_project_primer`.
+ *
+ * Returns the project's auto-generated AI Context Pack as a single
+ * markdown blob, token-budget aware. AI agents call this as their
+ * first read per session.
+ *
+ * What's actually in the primer (ORB-563):
+ *   - active milestones, ticket counts, recently-closed milestones
+ *   - top docs from the project space
+ * - structured project facts (the `primer_facts` table - workspace +
+ *     project rows)
+ *   - recent activity, when the operator enabled it
+ *   - repo briefings (e.g. CLAUDE.md / AGENTS.md) ONLY when the
+ *     operator configured `repoFiles` AND the API host has those files
+ *     on its local filesystem. Most Coolify / SaaS deployments do
+ *     neither - agents must NOT assume CLAUDE.md / AGENTS.md content
+ *     is in the primer. If the team relies on CLAUDE.md / AGENTS.md
+ *     content cross-deployment, those conventions belong in
+ *     `primer_facts` instead.
+ *
+ * Sections that didn't make the budget come back in
+ * `truncatedSections` so the agent can decide whether to bump the
+ * budget for a follow-up call.
+ */
+import { z } from 'zod';
+import { resolveProjectByKey } from './shared.js';
+export const getProjectPrimerToolConfig = {
+    title: 'Get project primer (AI Context Pack)',
+    description: 'Returns the project\'s auto-generated session primer in a single call: active milestones, ticket counts, recently-closed milestones, top docs, structured primer facts, and recent activity. Primer facts merge three scopes in order Workspace -> Project -> Personal: the Personal block ("Your preferences") is the calling user\'s own personal-scope facts, included only when that user has opted in (ai_preferences_enabled) and never showing another user\'s. Repo briefings (CLAUDE.md / AGENTS.md) are included ONLY when the operator configured them AND the API host can read those files from disk - most deployments will not have them, so do not assume CLAUDE.md / AGENTS.md content is in the response. Token-budget aware - pass `maxTokens` to constrain the output. Input is the project key (e.g. "ORB"), case-insensitive.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key, case-insensitive.'),
+        maxTokens: z.number().int().positive().max(200000).optional()
+            .describe('Cap the output. Default: the project\'s max_tokens.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeGetProjectPrimerHandler(client) {
+    return async ({ projectKey, maxTokens }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        const qs = new URLSearchParams({ format: 'json' });
+        if (maxTokens !== undefined)
+            qs.set('max_tokens', String(maxTokens));
+        const res = await client.get(`/projects/${project.id}/ai-primer?${qs.toString()}`);
+        // ORB-1104 - the trimmed-sections note is now appended in-band by
+        // assembleWithBudget, so res.markdown already carries it (and so do
+        // baked snapshots + the raw markdown route). No manual append here,
+        // otherwise it would double up.
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: res.markdown,
+                },
+            ],
+        };
+    };
+}

package/dist/tools/get-project.js

@@ -0,0 +1,77 @@
+/**
+ * ORB-244 Phase B - `orboto_get_project`.
+ *
+ * Returns metadata + milestones + labels + members for a project.
+ * Accepts the human-readable project key (`ACME`), case-insensitive
+ * - the API's `GET /projects/by-key/:key` does the lookup, the rest
+ * of the hydration (milestones + labels + members) comes from the
+ * `/projects/:id/*` endpoints that take the resolved UUID.
+ *
+ * Members endpoint returns a nested `{user: {...}, role: {...}}`
+ * shape; we flatten here into a card-friendly line.
+ */
+import { z } from 'zod';
+import { resolveProjectByKey } from './shared.js';
+export const getProjectToolConfig = {
+    title: 'Get project details',
+    description: 'Return a single project with its milestones, labels, and members. Input is the project key like "ACME" (case-insensitive).',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key (e.g. "ACME"). Case-insensitive.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeGetProjectHandler(client) {
+    return async ({ projectKey }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        // Parallel fan-out - the API doesn't have a single aggregate route
+        // for milestones+labels+members, and three parallel fetches beat a
+        // chain on the default Node HTTP pool.
+        const [milestones, labels, members] = await Promise.all([
+            client.get(`/projects/${project.id}/milestones`),
+            client.get(`/projects/${project.id}/labels`),
+            client.get(`/projects/${project.id}/members`),
+        ]);
+        const lines = [
+            `Project ${project.key} - ${project.name} (${project.status})`,
+            project.description ? `Description: ${project.description}` : null,
+            '',
+            `Milestones (${milestones.length}):`,
+            ...milestones.map((m) => `  - ${m.milestoneKey ? `${m.milestoneKey} · ` : ''}${m.name} [${m.status}]${m.endDate ? ` due ${m.endDate}` : ''}`),
+            '',
+            `Labels: ${labels.map((l) => l.name).join(', ') || '(none)'}`,
+            // ORB-1040 - only mention RACI when the project opted in.
+            project.raciEnabled ? 'RACI: enabled' : null,
+            '',
+            `Members (${members.length}):`,
+            ...members.map((m) => {
+                const name = m.user.fullName || m.user.email;
+                return ` - ${name} <${m.user.email}> - ${m.role.name}`;
+            }),
+        ].filter((l) => l !== null);
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                project: {
+                    // ORB-1042 - surface the UUID for the rare APIs that still need it
+                    // (most agent surfaces accept the key).
+                    id: project.id,
+                    key: project.key,
+                    name: project.name,
+                    status: project.status,
+                    description: project.description,
+                    // ORB-1040 - RACI is opt-in; agents must not raise/set RACI here
+                    // unless this is true.
+                    raciEnabled: project.raciEnabled ?? false,
+                },
+                milestones,
+                labels,
+                members: members.map((m) => ({
+                    userId: m.userId,
+                    fullName: m.user.fullName,
+                    email: m.user.email,
+                    roleName: m.role.name,
+                })),
+            },
+        };
+    };
+}

package/dist/tools/get-ticket.js

@@ -0,0 +1,321 @@
+/**
+ * ORB-244 Phase B - `orboto_get_ticket`.
+ *
+ * Returns a ticket's full context - description, comments, assignees,
+ * labels, checklists, git activity - in a shape the model can
+ * reason about without follow-up calls. Comments and checklists are
+ * fetched in parallel with the ticket payload; git activity is
+ * skipped when the ticket's `gitActivityCount` is 0 so we don't waste
+ * a round-trip on the common case.
+ *
+ * ORB-272: `/tickets/:id/comments` is cursor-paginated. We pull the
+ * first page (50 by default) - if the ticket has more, a footer line
+ * nudges the user to open it in the UI. AI agents asking "give me
+ * the full history" beyond 50 is a rare enough case not to fan out.
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+import { resolveTicketByKey } from './shared.js';
+const COMMENT_PAGE_SIZE = 50;
+export const getTicketToolConfig = {
+    title: 'Get ticket details',
+    description: 'Return a ticket\'s decision card: description, status, priority, milestone, assignees, labels, dates, estimate/logged time, checklist progress, parent + sub-ticket count - plus COUNTS for everything omitted (commentCount, gitActivityCount, attachmentCount, childCount). Full blocks are opt-in via `include` (ORB-1698): pass e.g. include: ["comments"] to get the comment bodies, ["git","attachments","children","raci","checklistItems"] likewise. Input is the ticket key like "ACME-42".',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3).describe('Ticket key like "ACME-42".'),
+        include: z.array(z.enum(['comments', 'git', 'attachments', 'children', 'raci', 'checklistItems']))
+            .optional()
+            .describe('Blocks to inline in full. Default: none (counts only).'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeGetTicketHandler(client) {
+    return async ({ ticketKey, include }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const inc = new Set(include ?? []);
+        const parentId = ticket.parentTicketId ?? null;
+        // ORB-1698 - the default response is the decision CARD: identity +
+        // description + progress + counts. The heavy blocks (comment bodies,
+        // git rows, checklist items) are fetched only when asked for via
+        // `include` - measured, they were the bulk of a 1.02 Mtok carry cost.
+        // Children + attachments have no count on the enriched row, so their
+        // (cheap, metadata-only) fetches stay - the RESPONSE carries only the
+        // count unless included.
+        const [enriched, parent, childrenPage, attachments, commentsPage, checklists, gitActivity] = await Promise.all([
+            // ORB-1023 - `resolveTicketByKey` hits the by-key endpoint, which
+            // returns a BARE ticket row (no statusCategory, assignees, labels,
+            // milestoneName, counts). Re-fetch the enriched by-id shape; falls
+            // back to the bare row on a 404.
+            client.get(`/projects/${ticket.projectId}/tickets/${ticket.id}`).catch(swallow404(null)),
+            // Parent ticket - only fetched when set. Lets the model say
+            // "this is sub-ticket of [ACME-10]" without a second tool call.
+            parentId
+                ? client.get(`/projects/${ticket.projectId}/tickets/${parentId}`).catch(swallow404(null))
+                : Promise.resolve(null),
+            // Children via the parentTicketId filter (API-side, O(children)).
+            // Cap at 50; anything bigger should use `orboto_list_tickets
+            // --parentTicketKey` and paginate explicitly.
+            client.get(`/projects/${ticket.projectId}/tickets?parentTicketId=${ticket.id}&limit=50`).catch(swallow404({ items: [], nextCursor: null })),
+            // ORB-1455 - attachments metadata so the agent knows files exist.
+            client.get(`/tickets/${ticket.id}/attachments`).catch(swallow404([])),
+            inc.has('comments')
+                ? client.get(`/tickets/${ticket.id}/comments?limit=${COMMENT_PAGE_SIZE}`).catch(swallow404({ items: [], nextCursor: null }))
+                : Promise.resolve({ items: [], nextCursor: null }),
+            inc.has('checklistItems')
+                ? client.get(`/tickets/${ticket.id}/checklists`).catch(swallow404([]))
+                : Promise.resolve([]),
+            inc.has('git')
+                ? client.get(`/tickets/${ticket.id}/git-activity`).catch(swallow404([]))
+                : Promise.resolve([]),
+        ]);
+        const comments = commentsPage.items;
+        const hasMoreComments = !!commentsPage.nextCursor;
+        const children = childrenPage.items;
+        // ORB-1023 - prefer the enriched by-id row (statusCategory, assignees,
+        // labels, milestoneName); fall back to the bare resolver row.
+        const full = enriched ?? ticket;
+        const commentCount = full.commentCount ?? (inc.has('comments') ? comments.length : 0);
+        const gitCount = full.gitActivityCount ?? (inc.has('git') ? gitActivity.length : 0);
+        const omitted = [];
+        if (!inc.has('comments') && commentCount > 0)
+            omitted.push(`comments (${commentCount})`);
+        if (!inc.has('git') && gitCount > 0)
+            omitted.push(`git (${gitCount})`);
+        if (!inc.has('attachments') && attachments.length > 0)
+            omitted.push(`attachments (${attachments.length})`);
+        if (!inc.has('children') && children.length > 0)
+            omitted.push(`children (${children.length})`);
+        if (!inc.has('checklistItems') && (full.checklistProgress?.total ?? 0) > 0)
+            omitted.push(`checklistItems (${full.checklistProgress.total})`);
+        const includeHint = omitted.length > 0
+            ? `Omitted blocks: ${omitted.join(', ')}. Re-call orboto_get_ticket with include: ["comments"|"git"|"attachments"|"children"|"raci"|"checklistItems"] for the ones you need.`
+            : undefined;
+        return {
+            content: [{ type: 'text', text: formatTicket(full, inc, comments, hasMoreComments, checklists, gitActivity, parent, children, attachments, includeHint) }],
+            structuredContent: {
+                // ORB-1179 - surface the uuid alongside the key.
+                id: full.id,
+                key: full.ticketKey,
+                title: full.title,
+                status: full.statusName ?? full.status,
+                statusCategory: full.statusCategory ?? null,
+                milestone: full.milestoneId
+                    ? { id: full.milestoneId, name: full.milestoneName ?? null }
+                    : null,
+                priority: full.priority,
+                type: full.type,
+                // ORB-1608 - role-aware commit policy. The API defaults unset
+                // rows to 'implementation'.
+                deliveryMode: full.deliveryMode ?? 'implementation',
+                dueDate: full.dueDate,
+                startDate: full.startDate,
+                isPrivate: full.isPrivate,
+                estimatedTimeMinutes: full.estimatedTimeMinutes,
+                loggedMinutes: full.loggedMinutes ?? 0,
+                // ORB-1605 - true when in_review, zero ingested git_activities,
+                // but the project HAS an active git connection: closing
+                // verification may be blocked on stalled ingestion.
+                waitingForGitIngestion: full.waitingForGitIngestion ?? false,
+                description: full.description ?? null,
+                // Hierarchy - null when no parent, array of summary rows for
+                // children (empty array when none). Sub-ticket consumers can
+                // decide to call orboto_get_ticket on each for the full detail.
+                parentTicket: parent ? {
+                    key: parent.ticketKey,
+                    title: parent.title,
+                    status: parent.statusName ?? parent.status,
+                    statusCategory: parent.statusCategory ?? null,
+                } : null,
+                childCount: children.length,
+                ...(inc.has('children') ? {
+                    children: children.map((c) => ({
+                        key: c.ticketKey,
+                        title: c.title,
+                        status: c.statusName ?? c.status,
+                        statusCategory: c.statusCategory ?? null,
+                    })),
+                } : {}),
+                assignees: full.assignees ?? [],
+                // ORB-1034 - RACI roster (R/A/C/I); opt-in via include: ["raci"]
+                // (assignees above stay the always-on Responsible+Accountable set).
+                ...(inc.has('raci') ? {
+                    raci: (full.raci ?? []).map((r) => ({ userId: r.userId, fullName: r.fullName, role: r.role })),
+                } : {}),
+                labels: (full.labels ?? []).map((l) => l.name),
+                // ORB-1698 - counts always; bodies opt-in. checklistProgress is the
+                // aggregate from the enriched row (items via include).
+                commentCount,
+                gitActivityCount: gitCount,
+                attachmentCount: attachments.length,
+                checklistProgress: full.checklistProgress ?? { done: 0, total: 0 },
+                ...(includeHint ? { includeHint } : {}),
+                ...(inc.has('comments') ? {
+                    comments: comments.map((c) => ({
+                        id: c.id, // ORB-1285 - needed to target a comment for edit/delete
+                        author: c.userName ?? null,
+                        body: c.content,
+                        createdAt: c.createdAt,
+                        editedAt: c.editedAt ?? null,
+                        isInternal: c.isInternal,
+                    })),
+                    commentsHasMore: hasMoreComments,
+                } : {}),
+                ...(inc.has('checklistItems') ? {
+                    checklists: checklists.map((cl) => ({
+                        title: cl.title,
+                        triggersDone: cl.triggersDone,
+                        progress: cl.progress,
+                        items: cl.items.map((i) => ({
+                            content: i.content,
+                            done: i.effectiveCompleted,
+                            // When the item links to another ticket, `effectiveCompleted`
+                            // mirrors that ticket's status-category instead of this item's
+                            // own checkbox. Surface the link so the model can explain
+                            // why the item is/isn't done.
+                            linkedTicket: i.linkedTicketKey ? {
+                                key: i.linkedTicketKey,
+                                title: i.linkedTicketTitle,
+                                statusCategory: i.linkedTicketStatusCategory,
+                            } : null,
+                        })),
+                    })),
+                } : {}),
+                ...(inc.has('git') ? {
+                    gitActivity: gitActivity.map((g) => ({
+                        type: g.type,
+                        state: g.state,
+                        title: g.title,
+                        url: g.url,
+                        author: g.authorName,
+                        createdAt: g.createdAt,
+                    })),
+                } : {}),
+                // ORB-1455 - attachments (id + metadata). Feed an id to
+                // orboto_get_attachment to view an image or fetch the bytes.
+                ...(inc.has('attachments') ? {
+                    attachments: attachments.map((a) => ({
+                        id: a.id,
+                        filename: a.filename,
+                        contentType: a.contentType,
+                        sizeBytes: a.sizeBytes,
+                        downloadUrl: a.downloadUrl ?? `/attachments/${a.id}`,
+                    })),
+                } : {}),
+            },
+        };
+    };
+}
+function swallow404(fallback) {
+    return (err) => {
+        if (err instanceof OrbotoApiError && err.status === 404)
+            return fallback;
+        throw err;
+    };
+}
+function formatTicket(ticket, inc, comments, hasMoreComments, checklists, gitActivity, parent, children, attachments, includeHint) {
+    const header = [
+        `[${ticket.ticketKey}] ${ticket.title}`,
+        `Status: ${ticket.statusName ?? ticket.status}  Priority: ${ticket.priority}  Type: ${ticket.type}`,
+        // ORB-1608 - only shown when it deviates from the 'implementation'
+        // default, so a fresh ticket's card stays uncluttered.
+        ticket.deliveryMode && ticket.deliveryMode !== 'implementation'
+            ? `Delivery mode: ${ticket.deliveryMode}`
+            : null,
+        // ORB-1605 - surface the stalled-ingestion signal right in the
+        // header so an agent checking "is this really done?" sees it
+        // before reading the (currently empty) git-activity section.
+        ticket.waitingForGitIngestion
+            ? '⏳ Waiting for Git ingestion - this project has an active git connection but no commits/PRs have landed for this ticket yet. Closing verification may be blocked on stalled ingestion, not on unfinished work - check manually before assuming it is unlinked.'
+            : null,
+        // ORB-1023 - show the milestone name (not the UUID) when set.
+        ticket.milestoneId ? `Milestone: ${ticket.milestoneName ?? '(unnamed)'}` : null,
+        ticket.dueDate ? `Due: ${ticket.dueDate}` : null,
+        parent ? `Parent: [${parent.ticketKey}] ${parent.title} (${parent.statusName ?? parent.status})` : null,
+        children.length > 0
+            ? `Sub-tickets: ${children.length} (${children.filter((c) => c.statusCategory !== 'done' && c.statusCategory !== 'wont_fix').length} open)`
+            : null,
+        ticket.assignees && ticket.assignees.length > 0
+            ? `Assignees: ${ticket.assignees.map((a) => a.fullName || a.email).join(', ')}`
+            : 'Assignees: (unassigned)',
+        // ORB-1034 - RACI summary, shown only when the project uses RACI and
+        // someone holds a non-Responsible role (Accountable / Consulted / Informed).
+        ticket.raci && ticket.raci.some((r) => r.role !== 'R')
+            ? `RACI: ${['A', 'R', 'C', 'I']
+                .map((role) => {
+                const people = ticket.raci.filter((r) => r.role === role);
+                return people.length ? `${role}: ${people.map((p) => p.fullName || p.email).join(', ')}` : null;
+            })
+                .filter(Boolean)
+                .join(' · ')}`
+            : null,
+        ticket.labels && ticket.labels.length > 0
+            ? `Labels: ${ticket.labels.map((l) => l.name).join(', ')}`
+            : null,
+    ].filter((s) => s !== null);
+    if (inc.has('children') && children.length > 0) {
+        header.push('', 'Children:');
+        for (const c of children) {
+            header.push(`  - [${c.ticketKey}] ${c.title} (${c.statusName ?? c.status})`);
+        }
+    }
+    const description = ticket.description
+        ? ['', '## Description', ticket.description]
+        : [];
+    const checklistLines = [];
+    if (!inc.has('checklistItems') && (ticket.checklistProgress?.total ?? 0) > 0) {
+        checklistLines.push('', `Checklists: ${ticket.checklistProgress.done}/${ticket.checklistProgress.total} done`);
+    }
+    if (inc.has('checklistItems') && checklists.length > 0) {
+        checklistLines.push('', '## Checklists');
+        for (const cl of checklists) {
+            const progressLabel = `${cl.progress.done}/${cl.progress.total}`;
+            checklistLines.push(`### ${cl.title} (${progressLabel})${cl.triggersDone ? ' · triggers done' : ''}`);
+            for (const i of cl.items) {
+                // Linked-ticket suffix on items that track another ticket - 
+                // lets the model say "item X is done because [ACME-42] shipped".
+                const link = i.linkedTicketKey
+                    ? ` ↪ [${i.linkedTicketKey}] ${i.linkedTicketTitle ?? ''} (${i.linkedTicketStatusCategory ?? 'unknown'})`
+                    : '';
+                checklistLines.push(`- [${i.effectiveCompleted ? 'x' : ' '}] ${i.content}${link}`);
+            }
+        }
+    }
+    const commentLines = [];
+    if (!inc.has('comments') && (ticket.commentCount ?? 0) > 0) {
+        commentLines.push('', `Comments: ${ticket.commentCount}`);
+    }
+    if (inc.has('comments') && comments.length > 0) {
+        const headerLine = hasMoreComments
+            ? `## Comments (${comments.length} shown, more in the UI)`
+            : `## Comments (${comments.length})`;
+        commentLines.push('', headerLine);
+        for (const c of comments) {
+            commentLines.push(`**${c.userName ?? '(unknown author)'}** - ${c.createdAt}${c.isInternal ? ' [internal]' : ''}`, c.content, '');
+        }
+    }
+    const gitLines = [];
+    if (!inc.has('git') && (ticket.gitActivityCount ?? 0) > 0) {
+        gitLines.push('', `Git activity: ${ticket.gitActivityCount}`);
+    }
+    if (inc.has('git') && gitActivity.length > 0) {
+        gitLines.push('', `## Git activity (${gitActivity.length})`);
+        for (const g of gitActivity) {
+            gitLines.push(`- ${g.type} ${g.state ? `[${g.state}]` : ''} ${g.title}${g.url ? ` - ${g.url}` : ''}`);
+        }
+    }
+    // ORB-1455 - attachments so the agent knows files exist. Feed an id to
+    // orboto_get_attachment to view an image or fetch the bytes.
+    const attachmentLines = [];
+    if (!inc.has('attachments') && attachments.length > 0) {
+        attachmentLines.push('', `Attachments: ${attachments.length}`);
+    }
+    if (inc.has('attachments') && attachments.length > 0) {
+        attachmentLines.push('', `## Attachments (${attachments.length})`);
+        for (const a of attachments) {
+            const kb = Math.round(a.sizeBytes / 1024);
+            attachmentLines.push(`- ${a.filename} (${kb} KB, ${a.contentType}) id=${a.id}`);
+        }
+        attachmentLines.push('Use orboto_get_attachment with an id to view an image or fetch bytes.');
+    }
+    const hintLines = includeHint ? ['', includeHint] : [];
+    return [...header, ...description, ...checklistLines, ...commentLines, ...gitLines, ...attachmentLines, ...hintLines].join('\n');
+}

package/dist/tools/get-timer.js

@@ -0,0 +1,62 @@
+/**
+ * ORB-244 Phase B - `orboto_get_timer`.
+ *
+ * Returns the caller's active stopwatch (or `null` when none is
+ * running). Useful for the model to answer "am I still tracking
+ * time on that bug from earlier?" without guessing.
+ *
+ * API shape: `GET /time/timer` returns `ActiveTimer | null` directly
+ * (not wrapped). ActiveTimer carries `ticketTitle` and `projectId`
+ * as joined fields but no `ticketKey` - so the ticket identifier is
+ * resolved the cheap way: first 8 chars of the UUID when no title
+ * is available, just the title otherwise.
+ */
+import { z } from 'zod';
+export const getTimerToolConfig = {
+    title: 'Get current timer',
+    description: 'Return the caller\'s currently-running stopwatch (or null if no timer is active).',
+    inputSchema: z.object({}).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeGetTimerHandler(client) {
+    return async () => {
+        // `/time/timer` returns the timer row directly, or `null`.
+        const timer = await client.get('/time/timer');
+        if (!timer) {
+            return {
+                content: [{ type: 'text', text: 'No active timer.' }],
+                structuredContent: { timer: null },
+            };
+        }
+        const isPaused = timer.pausedAt !== null;
+        const elapsedSinceStart = isPaused
+            ? 0
+            : Math.floor((Date.now() - new Date(timer.startedAt).getTime()) / 1000);
+        const totalSeconds = timer.accumulatedSeconds + elapsedSinceStart;
+        const minutes = Math.floor(totalSeconds / 60);
+        const ticketLabel = timer.ticketTitle ?? `(ticket ${timer.ticketId.slice(0, 8)})`;
+        const text = [
+            `Timer ${isPaused ? 'paused' : 'running'} on ${ticketLabel}`,
+            `Elapsed: ${minutes} min (${totalSeconds}s total)`,
+            `Started: ${timer.startedAt}`,
+            isPaused ? `Paused: ${timer.pausedAt}` : null,
+            timer.description ? `Note: ${timer.description}` : null,
+        ].filter((l) => l !== null).join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: {
+                timer: {
+                    ticketId: timer.ticketId,
+                    ticketTitle: timer.ticketTitle ?? null,
+                    projectId: timer.projectId ?? null,
+                    description: timer.description,
+                    startedAt: timer.startedAt,
+                    pausedAt: timer.pausedAt,
+                    accumulatedSeconds: timer.accumulatedSeconds,
+                    totalSeconds,
+                    paused: isPaused,
+                },
+            },
+        };
+    };
+}

package/dist/tools/help.js

@@ -0,0 +1,44 @@
+/**
+ * ORB-1741 - `orboto_help`: lazy full guidance for one tool.
+ *
+ * The manifest carries one-sentence summaries (the diet in
+ * tool-docs.ts); the complete guidance text - workflows, warnings, edge
+ * cases - is served HERE on demand, so a session only pays for the docs
+ * of tools it actually reasons about. Same pattern as deferred-tool
+ * schemas via ToolSearch.
+ */
+import { z } from 'zod';
+import { getToolDoc, listToolDocNames } from '../tool-docs.js';
+export const helpToolConfig = {
+    title: 'Full guidance for one orboto tool',
+    description: 'Return the complete guidance text (workflows, warnings, edge cases) for one orboto tool by name - manifest descriptions are one-line summaries, this is the rest. Call it before first use of an unfamiliar write tool.',
+    inputSchema: z.object({
+        tool: z.string().min(1).max(128).describe('Tool name, e.g. orboto_create_ticket.'),
+    }).shape,
+    outputSchema: z.object({
+        tool: z.string(),
+        guidance: z.string(),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeHelpHandler() {
+    return async (args) => {
+        const name = args.tool.trim();
+        const doc = getToolDoc(name) ?? getToolDoc(`orboto_${name}`);
+        if (!doc) {
+            const known = listToolDocNames();
+            return {
+                content: [{
+                        type: 'text',
+                        text: `No guidance registered for "${name}". Known tools (${known.length}): ${known.join(', ')}`,
+                    }],
+                structuredContent: { tool: name, guidance: '' },
+            };
+        }
+        const resolved = getToolDoc(name) ? name : `orboto_${name}`;
+        return {
+            content: [{ type: 'text', text: doc }],
+            structuredContent: { tool: resolved, guidance: doc },
+        };
+    };
+}