@tequila99/githuman 0.4.0 → 0.4.1

package/dist/server/routes/diff.js

@@ -1,40 +1,41 @@
 import { BadRequestError } from "../errors/http.js";
 import { Type } from '@sinclair/typebox';
-import { getStagedDiff, getUnstagedDiff, getBranchDiff, getCommitsDiff, getDiffSummaries, getFileDiff } from "../services/diff.service.js";
+import { getBranchDiff, getCommitsDiff, getDiffSummaries, getFileDiff } from "../services/diff.service.js";
 import { resolveWithinRepo } from "../services/git.service.js";
 import { errorMessage } from "../../shared/utils/error-message.js";
-const BranchQuery = Type.Object({
-    base: Type.String({ minLength: 1 })
-});
-const CommitsQuery = Type.Object({
-    from: Type.String({ minLength: 1 }),
-    to: Type.String({ minLength: 1 })
-});
-const SourceParams = Type.Object({
-    source: Type.Union([Type.Literal('staged'), Type.Literal('unstaged')])
-});
-const FileQuery = Type.Object({
-    path: Type.String({ minLength: 1 }),
-    oldPath: Type.Optional(Type.String({ minLength: 1 })),
-    status: Type.Union([
-        Type.Literal('added'),
-        Type.Literal('modified'),
-        Type.Literal('deleted'),
-        Type.Literal('renamed')
-    ])
-});
+import { BranchQuery, CommitsQuery, DiffFileSchema, DiffFileSummarySchema, FileQuery, SourceParams } from "../../shared/diff/schemas.js";
+import { ERROR_RESPONSES } from "../../shared/http/schemas.js";
+// OpenAPI group of these routes.
+const TAGS = ['diff'];
 export async function diffRoutes(app, opts) {
     const { repositoryPath } = opts;
     const typedApp = app.withTypeProvider();
-    typedApp.get('/api/diff/staged', async () => {
-        return getStagedDiff(repositoryPath);
-    });
-    typedApp.get('/api/diff/unstaged', async () => {
-        return getUnstagedDiff(repositoryPath);
-    });
     // Files without hunks, then one file with hunks: the list stays small (ADR 0033).
-    typedApp.get('/api/diff/:source/files', { schema: { params: SourceParams } }, async (request) => getDiffSummaries(repositoryPath, request.params.source));
-    typedApp.get('/api/diff/:source/file', { schema: { params: SourceParams, querystring: FileQuery } }, async (request) => {
+    typedApp.get('/api/diff/:source/files', {
+        schema: {
+            tags: TAGS,
+            summary: 'List changed files without hunks',
+            params: SourceParams,
+            response: {
+                200: Type.Array(DiffFileSummarySchema, {
+                    description: 'Changed files of the side.'
+                }),
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => getDiffSummaries(repositoryPath, request.params.source));
+    typedApp.get('/api/diff/:source/file', {
+        schema: {
+            tags: TAGS,
+            summary: 'Get one changed file with hunks',
+            params: SourceParams,
+            querystring: FileQuery,
+            response: {
+                200: { ...DiffFileSchema, description: 'The file with its hunks.' },
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => {
         const { path, oldPath, status } = request.query;
         // Only a path outside the repository is a bad request. Other errors stay server errors.
         try {
@@ -51,7 +52,20 @@ export async function diffRoutes(app, opts) {
             status
         });
     });
-    typedApp.get('/api/diff/branch', { schema: { querystring: BranchQuery } }, async (request) => {
+    typedApp.get('/api/diff/branch', {
+        schema: {
+            tags: TAGS,
+            summary: 'Diff of HEAD against a ref',
+            description: 'No UI calls it yet. It is kept for branch reviews.',
+            querystring: BranchQuery,
+            response: {
+                200: Type.Array(DiffFileSchema, {
+                    description: 'Changed files with hunks.'
+                }),
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => {
         try {
             return await getBranchDiff(repositoryPath, request.query.base);
         }
@@ -60,7 +74,20 @@ export async function diffRoutes(app, opts) {
             throw new BadRequestError(message, { cause: err });
         }
     });
-    typedApp.get('/api/diff/commits', { schema: { querystring: CommitsQuery } }, async (request) => {
+    typedApp.get('/api/diff/commits', {
+        schema: {
+            tags: TAGS,
+            summary: 'Diff between two refs',
+            description: 'No UI calls it yet. It is kept for commit reviews.',
+            querystring: CommitsQuery,
+            response: {
+                200: Type.Array(DiffFileSchema, {
+                    description: 'Changed files with hunks.'
+                }),
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => {
         try {
             return await getCommitsDiff(repositoryPath, request.query.from, request.query.to);
         }

package/dist/server/routes/events.js

@@ -1,8 +1,21 @@
 import { safeSend } from "../utils/sse.js";
+import { EventStreamSchema } from "../../shared/events/schemas.js";
 export async function eventRoutes(app, opts) {
     const { eventBus, instanceId } = opts;
     const hello = { instanceId };
-    app.get('/api/events', { sse: true }, async (request, reply) => {
+    app.get('/api/events', {
+        sse: true,
+        schema: {
+            tags: ['events'],
+            summary: 'Stream of review, comment and file changes',
+            response: {
+                200: {
+                    description: 'An SSE stream that stays open.',
+                    content: { 'text/event-stream': { schema: EventStreamSchema } }
+                }
+            }
+        }
+    }, async (request, reply) => {
         reply.sse.keepAlive();
         await reply.sse.send({ event: 'connected', data: hello });
         // The client can leave during the await; a later `onClose` would never run.

package/dist/server/routes/export.js

@@ -1,13 +1,30 @@
 import { Type } from '@sinclair/typebox';
 import { exportAsJson, exportAsMarkdown } from "../services/export.service.js";
-const ExportParams = Type.Object({ id: Type.String() });
-const ExportQuery = Type.Object({
-    format: Type.Union([Type.Literal('json'), Type.Literal('markdown')])
-});
+import { ExportQuery, ReviewExportSchema, ReviewIdParams } from "../../shared/reviews/schemas.js";
+import { ERROR_RESPONSES } from "../../shared/http/schemas.js";
 export async function exportRoutes(app, opts) {
     const { db, repositoryPath } = opts;
     const typedApp = app.withTypeProvider();
-    typedApp.get('/api/reviews/:id/export', { schema: { params: ExportParams, querystring: ExportQuery } }, async (request, reply) => {
+    typedApp.get('/api/reviews/:id/export', {
+        schema: {
+            tags: ['reviews'],
+            summary: 'Export a review with its comments',
+            params: ReviewIdParams,
+            querystring: ExportQuery,
+            response: {
+                200: {
+                    description: 'The review as JSON or as a markdown report.',
+                    content: {
+                        'application/json': { schema: ReviewExportSchema },
+                        'text/markdown': {
+                            schema: Type.String({ description: 'Markdown report.' })
+                        }
+                    }
+                },
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request, reply) => {
         if (request.query.format === 'json') {
             return exportAsJson(db, request.params.id);
         }

package/dist/server/routes/git.js

@@ -1,27 +1,29 @@
 import { BadRequestError } from "../errors/http.js";
-import { Type } from '@sinclair/typebox';
 import { getRepositoryInfo, stagePaths, unstagePaths, discardPaths, getFilesAtRef, getFileAtRef } from "../services/git.service.js";
-const TreeParams = Type.Object({
-    ref: Type.String({ minLength: 1 })
-});
-const FileContentQuery = Type.Object({
-    ref: Type.String({ minLength: 1 })
-});
-/** Body for `/stage` and `/unstage`: an omitted/empty `paths` means "all". */
-const OptionalPathsBody = Type.Object({
-    paths: Type.Optional(Type.Array(Type.String()))
-});
-/** Body for `/discard`: `paths` is required — no "discard everything". */
-const DiscardBody = Type.Object({
-    paths: Type.Array(Type.String(), { minItems: 1 })
-});
+import { DiscardBody, FileContentQuery, FileContentResponseSchema, FileParams, FileTreeResponseSchema, OkSchema, OptionalPathsBody, RepositoryInfoSchema, TreeParams } from "../../shared/git/schemas.js";
+import { ERROR_RESPONSES } from "../../shared/http/schemas.js";
+// OpenAPI group of these routes.
+const TAGS = ['git'];
 export async function gitRoutes(app, opts) {
     const { repositoryPath } = opts;
     const typedApp = app.withTypeProvider();
-    app.get('/api/git/info', async () => {
+    typedApp.get('/api/git/info', {
+        schema: {
+            tags: TAGS,
+            summary: 'Repository facts',
+            response: { 200: RepositoryInfoSchema, ...ERROR_RESPONSES }
+        }
+    }, async () => {
         return getRepositoryInfo(repositoryPath);
     });
-    typedApp.post('/api/git/stage', { schema: { body: OptionalPathsBody } }, async (request) => {
+    typedApp.post('/api/git/stage', {
+        schema: {
+            tags: TAGS,
+            summary: 'Stage paths',
+            body: OptionalPathsBody,
+            response: { 200: OkSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request) => {
         try {
             await stagePaths(repositoryPath, request.body.paths ?? []);
             return { ok: true };
@@ -31,7 +33,14 @@ export async function gitRoutes(app, opts) {
             throw new BadRequestError(message, { cause: err });
         }
     });
-    typedApp.post('/api/git/unstage', { schema: { body: OptionalPathsBody } }, async (request) => {
+    typedApp.post('/api/git/unstage', {
+        schema: {
+            tags: TAGS,
+            summary: 'Unstage paths',
+            body: OptionalPathsBody,
+            response: { 200: OkSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request) => {
         try {
             await unstagePaths(repositoryPath, request.body.paths ?? []);
             return { ok: true };
@@ -41,7 +50,14 @@ export async function gitRoutes(app, opts) {
             throw new BadRequestError(message, { cause: err });
         }
     });
-    typedApp.post('/api/git/discard', { schema: { body: DiscardBody } }, async (request) => {
+    typedApp.post('/api/git/discard', {
+        schema: {
+            tags: TAGS,
+            summary: 'Discard working-tree changes of paths',
+            body: DiscardBody,
+            response: { 200: OkSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request) => {
         try {
             await discardPaths(repositoryPath, request.body.paths);
             return { ok: true };
@@ -51,7 +67,14 @@ export async function gitRoutes(app, opts) {
             throw new BadRequestError(message, { cause: err });
         }
     });
-    typedApp.get('/api/git/tree/:ref', { schema: { params: TreeParams } }, async (request) => {
+    typedApp.get('/api/git/tree/:ref', {
+        schema: {
+            tags: TAGS,
+            summary: 'List files at a ref',
+            params: TreeParams,
+            response: { 200: FileTreeResponseSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request) => {
         const { ref } = request.params;
         try {
             const files = await getFilesAtRef(repositoryPath, ref);
@@ -62,7 +85,15 @@ export async function gitRoutes(app, opts) {
             throw new BadRequestError(message, { cause: err });
         }
     });
-    typedApp.get('/api/git/file/*', { schema: { querystring: FileContentQuery } }, async (request) => {
+    typedApp.get('/api/git/file/*', {
+        schema: {
+            tags: TAGS,
+            summary: 'Read one file at a ref',
+            params: FileParams,
+            querystring: FileContentQuery,
+            response: { 200: FileContentResponseSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request) => {
         const filePath = request.params['*'];
         const { ref } = request.query;
         if (!filePath) {

package/dist/server/routes/health.js

@@ -1,5 +1,12 @@
+import { HealthSchema } from "../../shared/app/schemas.js";
 export async function healthRoutes(app) {
-    app.get('/health', async () => {
+    app.withTypeProvider().get('/health', {
+        schema: {
+            tags: ['app'],
+            summary: 'Liveness check',
+            response: { 200: HealthSchema }
+        }
+    }, async () => {
         return { status: 'ok' };
     });
 }

package/dist/server/routes/openapi.js

@@ -0,0 +1,4 @@
+export async function openApiRoutes(app) {
+    // No authentication (ADR 0008): the spec tells no more than the API itself.
+    app.get('/api/openapi.json', { schema: { hide: true } }, async () => app.swagger());
+}

package/dist/server/routes/reviews.js

@@ -2,43 +2,41 @@ import { NotFoundError, BadRequestError } from "../errors/http.js";
 import { Type } from '@sinclair/typebox';
 import { createReview, getReview, getReviews, setReviewStatus, removeReview } from "../services/review.service.js";
 import { getRepositoryInfo } from "../services/git.service.js";
-const CreateReviewBody = Type.Object({
-    sourceType: Type.Optional(Type.Union([
-        Type.Literal('local'),
-        Type.Literal('staged'),
-        Type.Literal('unstaged'),
-        Type.Literal('branch'),
-        Type.Literal('commits')
-    ])),
-    sourceRef: Type.Optional(Type.String()),
-    baseRef: Type.Optional(Type.String()),
-    name: Type.Optional(Type.String())
-});
-const ReviewsQuery = Type.Object({
-    branch: Type.Optional(Type.String()),
-    search: Type.Optional(Type.String()),
-    createdFrom: Type.Optional(Type.String()),
-    createdTo: Type.Optional(Type.String()),
-    /** Comma-separated file paths — reviews matching any of them are returned. */
-    files: Type.Optional(Type.String())
-});
-const UpdateReviewBody = Type.Object({
-    status: Type.Optional(Type.Union([
-        Type.Literal('in_progress'),
-        Type.Literal('approved'),
-        Type.Literal('changes_requested')
-    ]))
-});
-const ReviewIdParams = Type.Object({ id: Type.String() });
+import { CreateReviewBody, ReviewIdParams, ReviewSchema, ReviewSummarySchema, ReviewsQuery, UpdateReviewBody } from "../../shared/reviews/schemas.js";
+import { ERROR_RESPONSES, NoContentSchema } from "../../shared/http/schemas.js";
+// OpenAPI group of these routes.
+const TAGS = ['reviews'];
 export async function reviewRoutes(app, opts) {
     const { repositoryPath, db, eventBus } = opts;
     const typedApp = app.withTypeProvider();
-    typedApp.post('/api/reviews', { schema: { body: CreateReviewBody } }, async (request, reply) => {
+    typedApp.post('/api/reviews', {
+        schema: {
+            tags: TAGS,
+            summary: 'Create a review from the current diff',
+            body: CreateReviewBody,
+            response: {
+                201: { ...ReviewSchema, description: 'The new review.' },
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request, reply) => {
         const review = await createReview(db, repositoryPath, request.body, eventBus);
         reply.code(201);
         return review;
     });
-    typedApp.get('/api/reviews', { schema: { querystring: ReviewsQuery } }, async (request) => {
+    typedApp.get('/api/reviews', {
+        schema: {
+            tags: TAGS,
+            summary: 'List reviews, newest first',
+            querystring: ReviewsQuery,
+            response: {
+                200: Type.Array(ReviewSummarySchema, {
+                    description: 'Reviews without snapshots.'
+                }),
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => {
         const { branch, search, createdFrom, createdTo, files } = request.query;
         const resolvedBranch = branch ?? (await getRepositoryInfo(repositoryPath)).branch;
         return getReviews(db, {
@@ -51,14 +49,35 @@ export async function reviewRoutes(app, opts) {
                 : undefined
         });
     });
-    typedApp.get('/api/reviews/:id', { schema: { params: ReviewIdParams } }, async (request) => {
+    typedApp.get('/api/reviews/:id', {
+        schema: {
+            tags: TAGS,
+            summary: 'Get a review with its snapshot',
+            params: ReviewIdParams,
+            response: { 200: ReviewSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request) => {
         const review = getReview(db, request.params.id);
         if (!review) {
             throw new NotFoundError(`Review ${request.params.id} not found`);
         }
         return review;
     });
-    typedApp.patch('/api/reviews/:id', { schema: { params: ReviewIdParams, body: UpdateReviewBody } }, async (request) => {
+    typedApp.patch('/api/reviews/:id', {
+        schema: {
+            tags: TAGS,
+            summary: 'Change the review status',
+            params: ReviewIdParams,
+            body: UpdateReviewBody,
+            response: {
+                200: {
+                    ...ReviewSummarySchema,
+                    description: 'The changed review without its snapshot.'
+                },
+                ...ERROR_RESPONSES
+            }
+        }
+    }, async (request) => {
         if (!request.body.status) {
             throw new BadRequestError('"status" is required');
         }
@@ -68,7 +87,14 @@ export async function reviewRoutes(app, opts) {
         }
         return updated;
     });
-    typedApp.delete('/api/reviews/:id', { schema: { params: ReviewIdParams } }, async (request, reply) => {
+    typedApp.delete('/api/reviews/:id', {
+        schema: {
+            tags: TAGS,
+            summary: 'Delete a review and its comments',
+            params: ReviewIdParams,
+            response: { 204: NoContentSchema, ...ERROR_RESPONSES }
+        }
+    }, async (request, reply) => {
         if (!getReview(db, request.params.id)) {
             throw new NotFoundError(`Review ${request.params.id} not found`);
         }

package/dist/server/services/agent/agent-session.js

@@ -195,6 +195,7 @@ export class AgentSession {
      * Changes a session setting (model, mode, …) and returns the agent's new
      * full set of options. Validated against what the agent itself offered, so
      * an unknown id or value is rejected here rather than sent on.
+     * `value` is `unknown`: the route schema gives it no type (see ConfigBody).
      */
     async setConfig(configId, value) {
         const connection = this.#connection;
@@ -208,9 +209,10 @@ export class AgentSession {
         if (!option) {
             throw new AgentConfigError(`Unknown setting "${configId}"`);
         }
-        if (option.type === 'boolean'
-            ? typeof value !== 'boolean'
-            : !option.options?.some(c => c.value === value)) {
+        if ((typeof value !== 'boolean' && typeof value !== 'string') ||
+            (option.type === 'boolean'
+                ? typeof value !== 'boolean'
+                : !option.options?.some(c => c.value === value))) {
             throw new AgentConfigError(`Invalid value for "${option.name}"`);
         }
         try {

package/dist/shared/agents/schemas.js

@@ -1,51 +1,140 @@
 import { Type } from '@sinclair/typebox';
 import { MAX_ATTACHMENT_BYTES, MAX_FILE_SEARCH_LIMIT } from "./constants.js";
-export const SessionParams = Type.Object({ id: Type.String() });
+import { DiffSourceNameSchema } from "../diff/schemas.js";
+import { Nullable } from "../utils/schemas.js";
+export const SessionParams = Type.Object({
+    id: Type.String({ description: 'Chat session id.' })
+});
 export const PermissionParams = Type.Object({
-    id: Type.String(),
-    requestId: Type.String()
+    id: Type.String({ description: 'Chat session id.' }),
+    requestId: Type.String({ description: 'Pending permission request id.' })
 });
 export const CreateSessionBody = Type.Object({
-    presetId: Type.String({ minLength: 1 }),
-    name: Type.Optional(Type.String({ maxLength: 60 })),
-    reviewId: Type.Optional(Type.String())
-});
-export const AutoApproveBody = Type.Object({ enabled: Type.Boolean() });
+    presetId: Type.String({
+        minLength: 1,
+        description: 'Preset from GET /api/agent/presets.'
+    }),
+    name: Type.Optional(Type.String({
+        maxLength: 60,
+        description: 'Chat name. Omitted: the server makes a unique one.'
+    })),
+    reviewId: Type.Optional(Type.String({ description: 'Review that the chat belongs to.' }))
+}, { description: 'A new chat session.' });
+export const AutoApproveBody = Type.Object({
+    enabled: Type.Boolean({
+        description: 'The server answers permission requests itself.'
+    })
+}, { description: 'Auto-approve switch of one session.' });
 export const FileSearchQuery = Type.Object({
-    q: Type.Optional(Type.String({ maxLength: 200 })),
-    limit: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_FILE_SEARCH_LIMIT }))
+    q: Type.Optional(Type.String({
+        maxLength: 200,
+        description: 'Fuzzy text to find in paths. Empty lists files.'
+    })),
+    limit: Type.Optional(Type.Integer({
+        minimum: 1,
+        maximum: MAX_FILE_SEARCH_LIMIT,
+        description: 'Maximum number of paths.'
+    }))
 });
 export const ContextItem = Type.Union([
     Type.Object({
-        kind: Type.Literal('diff'),
-        source: Type.Union([Type.Literal('staged'), Type.Literal('unstaged')]),
-        path: Type.Optional(Type.String({ minLength: 1 }))
-    }),
+        kind: Type.Literal('diff', { description: 'Live working-tree diff.' }),
+        source: DiffSourceNameSchema,
+        path: Type.Optional(Type.String({
+            minLength: 1,
+            description: 'One file of the diff. Omitted: the whole diff.'
+        }))
+    }, { description: 'The live diff of one side.' }),
     Type.Object({
-        kind: Type.Literal('file'),
-        path: Type.String({ minLength: 1 })
-    }),
-    Type.Object({ kind: Type.Literal('review'), reviewId: Type.String() }),
+        kind: Type.Literal('file', { description: 'A repository file.' }),
+        path: Type.String({
+            minLength: 1,
+            description: 'Repository-relative path. The agent reads the file.'
+        })
+    }, { description: 'A link to a repository file.' }),
     Type.Object({
-        kind: Type.Literal('attachment'),
-        name: Type.String({ minLength: 1, maxLength: 255 }),
-        mimeType: Type.String({ maxLength: 255 }),
+        kind: Type.Literal('review', { description: 'A review.' }),
+        reviewId: Type.String({ description: 'Review id.' })
+    }, { description: 'A review as markdown with its comments.' }),
+    Type.Object({
+        kind: Type.Literal('attachment', {
+            description: 'A file from the user.'
+        }),
+        name: Type.String({
+            minLength: 1,
+            maxLength: 255,
+            description: 'File name.'
+        }),
+        mimeType: Type.String({ maxLength: 255, description: 'MIME type.' }),
         data: Type.String({
-            maxLength: Math.ceil(MAX_ATTACHMENT_BYTES / 3) * 4
+            maxLength: Math.ceil(MAX_ATTACHMENT_BYTES / 3) * 4,
+            description: 'File content in base64.'
         })
-    })
-]);
+    }, { description: 'An uploaded file or a pasted image.' })
+], { description: 'Context of a prompt (docs/agent-context-uris.md).' });
 export const PromptBody = Type.Object({
-    text: Type.String({ minLength: 1 }),
-    context: Type.Optional(Type.Array(ContextItem, { maxItems: 20 }))
-});
+    text: Type.String({ minLength: 1, description: 'Message to the agent.' }),
+    context: Type.Optional(Type.Array(ContextItem, {
+        maxItems: 20,
+        description: 'Context items that go with the message.'
+    }))
+}, { description: 'A user message.' });
 export const PermissionBody = Type.Object({
-    optionId: Type.Optional(Type.String())
-});
+    optionId: Type.Optional(Type.String({
+        description: 'Option from the permission request. Omitted: the request is cancelled.'
+    }))
+}, { description: 'Answer to a permission request.' });
 export const ConfigBody = Type.Object({
-    configId: Type.String({ minLength: 1 }),
+    configId: Type.String({
+        minLength: 1,
+        description: 'Setting id from the config event.'
+    }),
     // No schema type on purpose: a Union/anyOf makes Fastify's Ajv coerce `true`
     // into the string "true", and a `type` array trips Ajv's strictTypes. The
     // session checks the value against the option the agent actually offered.
-    value: Type.Unsafe({})
+    value: Type.Unsafe({
+        description: 'A select value (string) or a boolean.'
+    })
+}, { description: 'A new value of an agent setting.' });
+export const AgentPresetInfoSchema = Type.Object({
+    id: Type.String({ description: 'Preset id.' }),
+    title: Type.String({ description: 'Name in the UI.' }),
+    available: Type.Boolean({
+        description: 'The launcher binary is in PATH. Says nothing about login or auth.'
+    }),
+    autoApprovesEdits: Type.Boolean({
+        description: 'The agent applies edits without permission requests.'
+    })
+}, { description: 'An ACP agent that can start a chat.' });
+export const AgentSessionStatusSchema = Type.Union([
+    Type.Literal('starting'),
+    Type.Literal('ready'),
+    Type.Literal('busy'),
+    Type.Literal('closed')
+], { description: 'Session state.' });
+export const AgentSessionInfoSchema = Type.Object({
+    id: Type.String({ description: 'Chat session id.' }),
+    presetId: Type.String({ description: 'Preset of the agent.' }),
+    name: Type.String({ description: 'Chat name in the UI.' }),
+    status: AgentSessionStatusSchema,
+    reviewId: Nullable(Type.String({ description: 'Review of the chat. Else null.' })),
+    autoApprove: Type.Boolean({
+        description: 'The server answers permission requests itself.'
+    }),
+    error: Nullable(Type.String({
+        description: 'Why the session could not start. Else null.'
+    }))
+}, { description: 'A chat session.' });
+export const AgentFileSearchResponseSchema = Type.Object({
+    files: Type.Array(Type.String(), {
+        description: 'Repository-relative paths, best match first.'
+    })
+}, { description: 'Files for the context picker.' });
+export const AgentEventsHeaders = Type.Object({
+    'last-event-id': Type.Optional(Type.String({
+        description: 'Last event id that the client got. Events after it come again.'
+    }))
+});
+export const AgentStreamSchema = Type.String({
+    description: 'Server-sent events: connected, then agent (AgentStreamEnvelope, SSE id = event id), state (AgentSessionState), gap ({ sessionId }) and sessions (reread the list).'
 });

package/dist/shared/app/schemas.js

@@ -0,0 +1,7 @@
+import { Type } from '@sinclair/typebox';
+export const AppInfoSchema = Type.Object({
+    version: Type.String({ description: 'githuman version from package.json.' })
+}, { description: 'Facts about the running server.' });
+export const HealthSchema = Type.Object({
+    status: Type.Literal('ok', { description: 'Always "ok".' })
+}, { description: 'The server is up.' });