@scrylog/cli 0.1.0

package/src/api/routes/webhooks/claude.ts

@@ -0,0 +1,161 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { DaemonStore } from "../../../daemon/store";
+import type { GitCollector } from "../../../daemon/collectors/git";
+import type { Logger } from "../../../shared/logger";
+import type { ClaudeWebhookPayload } from "../../models/claude";
+import { isMetadataOnlyEvent } from "../../services/claude-session";
+import { ValidationError } from "../../lib/errors";
+import { WebhookRouteKey } from "../../docs/webhooks.keys";
+import { defineRoute } from "../../lib/route";
+
+export function createClaudeWebhookRouter(store: DaemonStore, logger: Logger, gitCollector?: GitCollector): OpenAPIHono {
+  const router = new OpenAPIHono();
+
+  router.openapi(defineRoute(WebhookRouteKey.WEBHOOK_CLAUDE), async (c) => {
+    const payload = c.req.valid("json") as ClaudeWebhookPayload;
+
+    const {
+      sessionId,
+      eventType,
+      eventTime,
+      hookSeq,
+      state,
+      hasAttention,
+      attentionKind,
+      summary,
+      activeTool,
+      toolName,
+      toolInputSummary,
+      toolResultStatus,
+      permissionMode,
+      startSource,
+      endReason,
+      errorType,
+      agentId,
+      agentType,
+      transcriptPath,
+      currentPath,
+      lastActivity,
+      parentSessionId,
+    } = payload;
+
+    if (!sessionId || typeof sessionId !== "string") {
+      throw new ValidationError("sessionId required");
+    }
+
+    const storeId = `claude:${sessionId}`;
+    if (eventType === "SessionEnd") {
+      store.markLocalCommand(sessionId);
+      const existing = store.getSession(storeId);
+      if (existing) {
+        store.upsertSession({
+          ...existing,
+          state: "idle",
+          hasAttention: false,
+          summary: summary ?? existing.summary ?? "Claude session ended",
+          lastActivity: lastActivity ?? Date.now(),
+          detectionSource: "claude-hook",
+          claude: {
+            sessionId,
+            transcriptPath: transcriptPath ?? existing.claude?.transcriptPath ?? "",
+            ...(eventType !== undefined ? { hookEventType: eventType } : {}),
+            ...(eventTime !== undefined ? { hookEventTime: eventTime } : {}),
+            ...(hookSeq !== undefined ? { hookSeq } : {}),
+            ...(endReason !== undefined ? { endReason } : {}),
+            ...(errorType !== undefined ? { errorType } : {}),
+          },
+        });
+      }
+
+      logger.info("webhook", "claude session ended", { event: "session.ended", tool: "claude", sessionId, reason: endReason });
+      return c.json({ ok: true as const }, 200);
+    }
+
+    const existing = store.getSession(storeId);
+
+    if (existing) {
+      const existingSeq = existing.claude?.hookSeq;
+      if (typeof hookSeq === "number" && typeof existingSeq === "number" && hookSeq < existingSeq) {
+        logger.debug("webhook", "claude hook rejected — stale sequence", { sessionId, hookSeq, existingSeq });
+        return c.json({ ok: true as const, skipped: "stale-sequence" }, 200);
+      }
+    }
+
+    const isStateBearing = !isMetadataOnlyEvent(eventType ?? "");
+
+    logger.debug("webhook", "claude hook received", { sessionId, state, eventType });
+
+    if (existing) {
+      store.upsertSession({
+        ...existing,
+        ...(isStateBearing && state !== undefined ? { state } : {}),
+        ...(isStateBearing && hasAttention !== undefined ? { hasAttention } : {}),
+        ...(attentionKind !== undefined ? { attentionKind } : {}),
+        ...(summary !== undefined ? { summary } : {}),
+        ...(activeTool !== undefined ? { activeTool } : {}),
+        ...(!isStateBearing && currentPath !== undefined ? { currentPath } : {}),
+        ...(currentPath && !existing.project && gitCollector ? { project: gitCollector.resolve(currentPath) } : {}),
+        ...(isStateBearing ? {} : existing.currentPath && !currentPath ? {} : {}),
+        lastActivity: lastActivity ?? Date.now(),
+        detectionSource: "claude-hook",
+        ...(parentSessionId ? { parentSessionId } : {}),
+        claude: {
+          sessionId,
+          transcriptPath: transcriptPath ?? existing.claude?.transcriptPath ?? "",
+          ...(eventType !== undefined ? { hookEventType: eventType } : {}),
+          ...(eventTime !== undefined ? { hookEventTime: eventTime } : {}),
+          ...(hookSeq !== undefined ? { hookSeq } : {}),
+          ...(permissionMode !== undefined ? { permissionMode } : {}),
+          ...(startSource !== undefined ? { startSource } : {}),
+          ...(endReason !== undefined ? { endReason } : {}),
+          ...(errorType !== undefined ? { errorType } : {}),
+          ...(attentionKind !== undefined ? { attentionKind } : {}),
+          ...(toolName !== undefined ? { toolName } : {}),
+          ...(toolInputSummary !== undefined ? { toolInputSummary } : {}),
+          ...(toolResultStatus !== undefined ? { toolResultStatus } : {}),
+          ...(agentId !== undefined ? { agentId } : {}),
+          ...(agentType !== undefined ? { agentType } : {}),
+        },
+      });
+    } else {
+      store.upsertSession({
+        id: storeId,
+        source: "standalone",
+        tool: "claude",
+        state: (isStateBearing ? state : undefined) ?? "idle",
+        summary: summary ?? "Claude session",
+        lastActivity: lastActivity ?? Date.now(),
+        detectionSource: "claude-hook",
+        hasAttention: isStateBearing ? (hasAttention ?? false) : false,
+        activeTool,
+        currentPath,
+        ...(currentPath && gitCollector ? { project: gitCollector.resolve(currentPath) } : {}),
+        ...(parentSessionId ? { parentSessionId } : {}),
+        claude: {
+          sessionId,
+          transcriptPath: transcriptPath ?? "",
+          ...(eventType !== undefined ? { hookEventType: eventType } : {}),
+          ...(eventTime !== undefined ? { hookEventTime: eventTime } : {}),
+          ...(hookSeq !== undefined ? { hookSeq } : {}),
+          ...(permissionMode !== undefined ? { permissionMode } : {}),
+          ...(startSource !== undefined ? { startSource } : {}),
+          ...(endReason !== undefined ? { endReason } : {}),
+          ...(errorType !== undefined ? { errorType } : {}),
+          ...(attentionKind !== undefined ? { attentionKind } : {}),
+          ...(toolName !== undefined ? { toolName } : {}),
+          ...(toolInputSummary !== undefined ? { toolInputSummary } : {}),
+          ...(toolResultStatus !== undefined ? { toolResultStatus } : {}),
+          ...(agentId !== undefined ? { agentId } : {}),
+          ...(agentType !== undefined ? { agentType } : {}),
+        },
+      });
+
+      logger.debug("webhook", "claude stub session created from hook", { event: "session.upsert_from_webhook", tool: "claude", sessionId, state });
+    }
+
+    store.syncChildSessionIds();
+    return c.json({ ok: true as const }, 200);
+  });
+
+  return router;
+}

package/src/api/routes/webhooks/codex.ts

@@ -0,0 +1,175 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { DaemonStore } from "../../../daemon/store";
+import type { GitCollector } from "../../../daemon/collectors/git";
+import type { Logger } from "../../../shared/logger";
+import type { SessionModel } from "../../../shared/types";
+import type { CodexWebhookPayload } from "../../models/codex";
+import { isMetadataOnlyEvent } from "../../services/codex-session";
+import { ValidationError } from "../../lib/errors";
+import { WebhookRouteKey } from "../../docs/webhooks.keys";
+import { defineRoute } from "../../lib/route";
+
+export function createCodexWebhookRouter(store: DaemonStore, logger: Logger, gitCollector?: GitCollector): OpenAPIHono {
+  const router = new OpenAPIHono();
+
+  router.openapi(defineRoute(WebhookRouteKey.WEBHOOK_CODEX), async (c) => {
+    const payload = c.req.valid("json") as CodexWebhookPayload;
+
+    const {
+      sessionId,
+      eventType,
+      eventTime,
+      hookSeq,
+      state,
+      hasAttention,
+      attentionKind,
+      summary,
+      activeTool,
+      model,
+      toolName,
+      toolInputSummary,
+      toolResultStatus,
+      permissionMode,
+      startSource,
+      endReason,
+      transcriptPath,
+      currentPath,
+      lastActivity,
+      parentSessionId,
+      forkedFromId,
+      turnId,
+      agentId,
+      agentType,
+    } = payload;
+
+    if (!sessionId || typeof sessionId !== "string") {
+      throw new ValidationError("sessionId required");
+    }
+
+    const storeId = `codex:${sessionId}`;
+    const hasActiveChildren = () => store.getSessions().some(
+      (s) => s.parentSessionId === storeId && (s.state === "working" || s.state === "waiting-input"),
+    );
+
+    // Stop with no continuation is the terminal event for Codex (no SessionEnd)
+    if (eventType === "Stop") {
+      const existing = store.getSession(storeId);
+      if (existing) {
+        const resolvedState: SessionModel["state"] =
+          (state === "waiting-input" || state === "error") ? state : "idle";
+        store.upsertSession({
+          ...existing,
+          state: resolvedState,
+          hasAttention: resolvedState === "waiting-input" ? true : false,
+          summary: summary ?? existing.summary ?? "Codex session ended",
+          lastActivity: lastActivity ?? Date.now(),
+          detectionSource: "codex-hook",
+          codex: {
+            sessionId,
+            transcriptPath: transcriptPath ?? existing.codex?.transcriptPath ?? "",
+            ...(eventType !== undefined ? { hookEventType: eventType } : {}),
+            ...(eventTime !== undefined ? { hookEventTime: eventTime } : {}),
+            ...(hookSeq !== undefined ? { hookSeq } : {}),
+            ...(endReason !== undefined ? { endReason } : {}),
+          },
+        });
+      }
+
+      if (!hasActiveChildren()) {
+        store.markLocalCommand(sessionId);
+      }
+      logger.info("webhook", "codex session ended", { event: "session.ended", tool: "codex", sessionId, reason: endReason });
+      return c.json({ ok: true as const }, 200);
+    }
+
+    const existing = store.getSession(storeId);
+
+    if (existing) {
+      const existingSeq = existing.codex?.hookSeq;
+      if (typeof hookSeq === "number" && typeof existingSeq === "number" && hookSeq < existingSeq) {
+        logger.debug("webhook", "codex hook rejected — stale sequence", { sessionId, hookSeq, existingSeq });
+        return c.json({ ok: true as const, skipped: "stale-sequence" }, 200);
+      }
+    }
+
+    const isStateBearing = !isMetadataOnlyEvent(eventType ?? "");
+
+    logger.debug("webhook", "codex hook received", { sessionId, state, eventType });
+
+    if (existing) {
+      store.upsertSession({
+        ...existing,
+        ...(isStateBearing && state !== undefined ? { state } : {}),
+        ...(isStateBearing && hasAttention !== undefined ? { hasAttention } : {}),
+        ...(attentionKind !== undefined ? { attentionKind } : {}),
+        ...(summary !== undefined ? { summary } : {}),
+        ...(activeTool !== undefined ? { activeTool } : {}),
+        ...(!isStateBearing && currentPath !== undefined ? { currentPath } : {}),
+        ...(currentPath && !existing.project && gitCollector ? { project: gitCollector.resolve(currentPath) } : {}),
+        lastActivity: lastActivity ?? Date.now(),
+        detectionSource: "codex-hook",
+        ...(parentSessionId ? { parentSessionId } : {}),
+        codex: {
+          sessionId,
+          transcriptPath: transcriptPath ?? existing.codex?.transcriptPath ?? "",
+          ...(eventType !== undefined ? { hookEventType: eventType } : {}),
+          ...(eventTime !== undefined ? { hookEventTime: eventTime } : {}),
+          ...(hookSeq !== undefined ? { hookSeq } : {}),
+          ...(permissionMode !== undefined ? { permissionMode } : {}),
+          ...(startSource !== undefined ? { startSource } : {}),
+          ...(endReason !== undefined ? { endReason } : {}),
+          ...(model !== undefined ? { model } : {}),
+          ...(toolName !== undefined ? { toolName } : {}),
+          ...(toolInputSummary !== undefined ? { toolInputSummary } : {}),
+          ...(toolResultStatus !== undefined ? { toolResultStatus } : {}),
+          ...(attentionKind !== undefined ? { attentionKind } : {}),
+          ...(turnId !== undefined ? { turnId } : {}),
+          ...(agentId !== undefined ? { agentId } : {}),
+          ...(agentType !== undefined ? { agentType } : {}),
+          ...(forkedFromId !== undefined ? { forkedFromId } : {}),
+        },
+      });
+    } else {
+      store.upsertSession({
+        id: storeId,
+        source: "standalone",
+        tool: "codex",
+        state: (isStateBearing ? state : undefined) ?? "idle",
+        summary: summary ?? "Codex session",
+        lastActivity: lastActivity ?? Date.now(),
+        detectionSource: "codex-hook",
+        hasAttention: isStateBearing ? (hasAttention ?? false) : false,
+        activeTool,
+        currentPath,
+        ...(currentPath && gitCollector ? { project: gitCollector.resolve(currentPath) } : {}),
+        ...(parentSessionId ? { parentSessionId } : {}),
+        codex: {
+          sessionId,
+          transcriptPath: transcriptPath ?? "",
+          ...(eventType !== undefined ? { hookEventType: eventType } : {}),
+          ...(eventTime !== undefined ? { hookEventTime: eventTime } : {}),
+          ...(hookSeq !== undefined ? { hookSeq } : {}),
+          ...(permissionMode !== undefined ? { permissionMode } : {}),
+          ...(startSource !== undefined ? { startSource } : {}),
+          ...(endReason !== undefined ? { endReason } : {}),
+          ...(model !== undefined ? { model } : {}),
+          ...(toolName !== undefined ? { toolName } : {}),
+          ...(toolInputSummary !== undefined ? { toolInputSummary } : {}),
+          ...(toolResultStatus !== undefined ? { toolResultStatus } : {}),
+          ...(attentionKind !== undefined ? { attentionKind } : {}),
+          ...(turnId !== undefined ? { turnId } : {}),
+          ...(agentId !== undefined ? { agentId } : {}),
+          ...(agentType !== undefined ? { agentType } : {}),
+          ...(forkedFromId !== undefined ? { forkedFromId } : {}),
+        },
+      });
+
+      logger.debug("webhook", "codex stub session created from hook", { event: "session.upsert_from_webhook", tool: "codex", sessionId, state });
+    }
+
+    store.syncChildSessionIds();
+    return c.json({ ok: true as const }, 200);
+  });
+
+  return router;
+}

package/src/api/routes/webhooks/opencode.ts

@@ -0,0 +1,107 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { ScrylogConfig } from "../../../shared/config";
+import type { DaemonStore } from "../../../daemon/store";
+import type { Logger } from "../../../shared/logger";
+import type { SessionModel } from "../../../shared/types";
+import type { OpencodeWebhookPayload } from "../../models/opencode";
+import { mapHookState, extractSessionParentId } from "../../services/opencode-session";
+import { WebhookRouteKey } from "../../docs/webhooks.keys";
+import { defineRoute } from "../../lib/route";
+
+export function createOpencodeWebhookRouter(store: DaemonStore, config: ScrylogConfig, logger: Logger): OpenAPIHono {
+  const router = new OpenAPIHono();
+
+  router.openapi(defineRoute(WebhookRouteKey.WEBHOOK_OPENCODE), async (c) => {
+    const payload = c.req.valid("json") as OpencodeWebhookPayload;
+    const { event } = payload;
+
+    logger.debug("webhook", "received", {
+      event: "integration.event_received",
+      webhookEvent: event,
+      sessionID: payload.sessionID ?? payload.info?.id,
+      directory: payload.info?.directory ?? payload.directory,
+    });
+
+    if (config.opencode.mode === "sse") {
+      logger.debug("webhook", "skipped: opencode-mode-sse", { event: "integration.event_skipped", webhookEvent: event, reason: "opencode-mode-sse" });
+      return c.json({ ok: true as const, skipped: "opencode-mode-sse" }, 200);
+    }
+
+    const rawId = payload.sessionID ?? payload.info?.id;
+    if (!rawId && event !== "session.created") {
+      logger.debug("webhook", "skipped: no sessionID", { event: "integration.event_skipped", webhookEvent: event, reason: "no-session-id" });
+      return c.json({ ok: true as const, skipped: "no sessionID" }, 200);
+    }
+
+    if (event === "session.deleted" && rawId) {
+      logger.debug("webhook", "session.deleted", { event: "integration.event_received", tool: "opencode", sessionId: rawId });
+      store.removeSession(`opencode:${rawId}`);
+      return c.json({ ok: true as const }, 200);
+    }
+
+    if (rawId) {
+      const storeId = `opencode:${rawId}`;
+      const existing = store.getSession(storeId);
+      const { state, hasAttention, pendingAttentionCount } = mapHookState(event, payload, existing);
+
+      const title = payload.info?.title ?? payload.title ?? existing?.summary ?? "OpenCode session";
+      const directory = payload.info?.directory ?? payload.directory ?? existing?.currentPath;
+      const parentSessionId = extractSessionParentId(event, payload, existing);
+      const timeUpdated = payload.info?.time?.updated ?? Date.now();
+
+      if (payload.info?.parentID && payload.info.parentID !== parentSessionId?.replace(/^opencode:/, "")) {
+        logger.debug("webhook", "ignoring non-session parentID", {
+          event: "integration.event_skipped",
+          webhookEvent: event,
+          sessionId: rawId,
+          parentID: payload.info.parentID,
+        });
+      }
+
+      if (existing) {
+        const stateChanged = state !== existing.state;
+        const merged: SessionModel = {
+          ...existing,
+          state,
+          hasAttention,
+          summary: title,
+          currentPath: directory ?? existing.currentPath,
+          parentSessionId,
+          lastActivity: stateChanged ? Date.now() : Math.max(existing.lastActivity, timeUpdated),
+          opencode: {
+            ...existing.opencode,
+            sessionId: rawId,
+            instanceUrl: existing.opencode?.instanceUrl ?? "",
+            ...(pendingAttentionCount !== undefined ? { pendingAttentionCount } : {}),
+          },
+        };
+        logger.debug("webhook", "upsert existing session", { event: "session.upsert_from_webhook", webhookEvent: event, sessionId: rawId, state: merged.state });
+        store.upsertSession(merged);
+      } else {
+        const newSession: SessionModel = {
+          id: storeId,
+          source: "standalone",
+          tool: "opencode",
+          state,
+          summary: title,
+          lastActivity: timeUpdated,
+          detectionSource: "opencode-hook",
+          hasAttention,
+          currentPath: directory,
+          parentSessionId,
+          opencode: {
+            sessionId: rawId,
+            instanceUrl: "",
+            ...(pendingAttentionCount !== undefined ? { pendingAttentionCount } : {}),
+          },
+        };
+        logger.debug("webhook", "upsert new session", { event: "session.upsert_from_webhook", webhookEvent: event, sessionId: rawId, state, directory });
+        store.upsertSession(newSession);
+      }
+    }
+
+    return c.json({ ok: true as const }, 200);
+  });
+
+  return router;
+}

package/src/api/routes.ts

@@ -0,0 +1,93 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { Scalar } from "@scalar/hono-api-reference";
+import { createMarkdownFromOpenApi } from "@scalar/openapi-to-markdown";
+import { cors } from "hono/cors";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { ScrylogConfig } from "../shared/config";
+import type { DaemonStore } from "../daemon/store";
+import type { GitCollector } from "../daemon/collectors/git";
+import type { Logger } from "../shared/logger";
+import { NOOP_LOGGER } from "../shared/logger";
+import { ApiError } from "./lib/errors";
+import { createSystemRouter } from "./routes/system";
+import { createSessionsRouter } from "./routes/sessions";
+import { createUsageRouter } from "./routes/usage";
+import { createOpencodeWebhookRouter } from "./routes/webhooks/opencode";
+import { createClaudeWebhookRouter } from "./routes/webhooks/claude";
+import { createCodexWebhookRouter } from "./routes/webhooks/codex";
+import { createBearerAuthMiddleware } from "./lib/auth";
+
+export function createApiApp(
+  store: DaemonStore,
+  config: ScrylogConfig,
+  logger: Logger = NOOP_LOGGER,
+  gitCollector?: GitCollector,
+): OpenAPIHono {
+  const app = new OpenAPIHono();
+
+  app.onError((err, c) => {
+    if (err instanceof ApiError) {
+      return c.json({ error: err.message, code: err.code }, err.status as ContentfulStatusCode);
+    }
+    logger.debug("api", "unhandled error", { message: err.message });
+    return c.json({ error: "Internal server error", code: "INTERNAL_ERROR" }, 500);
+  });
+
+  app.notFound((c) => c.json({ error: "Not found", code: "NOT_FOUND" }, 404));
+
+  if (config.cors.enabled) {
+    app.use("*", cors({
+      origin: config.cors.origins,
+      allowMethods: config.cors.methods,
+      allowHeaders: config.cors.allowedHeaders,
+      exposeHeaders: config.cors.exposedHeaders,
+      credentials: config.cors.credentials,
+      maxAge: config.cors.maxAge,
+    }));
+  }
+
+  app.use(createBearerAuthMiddleware(config.api.bearerToken));
+
+  app.route("/api", createSystemRouter(store, config, logger));
+  app.route("/api", createSessionsRouter(store, config));
+  app.route("/api", createUsageRouter(store));
+  app.route("/api/webhook", createOpencodeWebhookRouter(store, config, logger));
+  app.route("/api/webhook", createClaudeWebhookRouter(store, logger, gitCollector));
+  app.route("/api/webhook", createCodexWebhookRouter(store, logger, gitCollector));
+
+  app.openAPIRegistry.registerComponent("securitySchemes", "BearerAuth", {
+    type: "http",
+    scheme: "bearer",
+    description: "Bearer token authentication (only enforced when api.bearerToken is configured)",
+  });
+
+  app.doc("/api/openapi.json", {
+    openapi: "3.0.0",
+    info: {
+      title: "scrylog API",
+      version: "1.0.0",
+      description: "scrylogd daemon HTTP API. Bearer auth is enforced on protected endpoints when api.bearerToken is configured.",
+    },
+  });
+
+  app.get("/api/docs", Scalar({ url: "/api/openapi.json" }));
+
+  app.get("/api/llms.txt", async (c) => {
+    const specUrl = new URL("/api/openapi.json", c.req.url);
+    const spec = await fetch(specUrl).then((r) => r.text());
+    const markdown = await createMarkdownFromOpenApi(spec);
+    return c.text(markdown);
+  });
+
+  return app;
+}
+
+/** @deprecated use createApiApp directly */
+export function createRouteHandler(
+  store: DaemonStore,
+  config: ScrylogConfig,
+  logger: Logger = NOOP_LOGGER,
+  gitCollector?: GitCollector,
+): (request: Request) => Response | Promise<Response> {
+  return createApiApp(store, config, logger, gitCollector).fetch;
+}

package/src/api/schemas/common.ts

@@ -0,0 +1,21 @@
+import { z } from "@hono/zod-openapi";
+
+export const ApiErrorSchema = z.object({
+  error: z.string().openapi({ example: "Session not found" }),
+});
+
+export const WebhookOkSchema = z.object({
+  ok: z.literal(true),
+  skipped: z.string().optional().openapi({ example: "stale-sequence" }),
+});
+
+// Session IDs follow prefix:suffix format (claude:uuid, opencode:ses_xxx, tmux:1:0.0).
+// Rejects path traversal characters and shell metacharacters.
+export const SessionIdParamSchema = z.object({
+  id: z
+    .string()
+    .min(1)
+    .max(200)
+    .regex(/^[a-zA-Z0-9:_\-.]+$/, "Invalid session ID")
+    .openapi({ param: { name: "id", in: "path" }, example: "claude:abc-123" }),
+});

package/src/api/schemas/sessions.ts

@@ -0,0 +1,72 @@
+import { z } from "@hono/zod-openapi";
+
+const SessionStateSchema = z.enum(["working", "idle", "waiting-input", "error", "shell", "unknown"]);
+const SessionToolSchema = z.enum(["opencode", "claude", "codex", "copilotcli", "shell", "unknown"]);
+
+const ProjectInfoSchema = z.object({
+  displayName: z.string(),
+  compactLabel: z.string(),
+  branch: z.string().optional(),
+  isGitRepository: z.boolean().optional(),
+  sourcePath: z.string().optional(),
+  gitRootPath: z.string().optional(),
+  repositoryIdentityPath: z.string().optional(),
+});
+
+const TmuxInfoSchema = z.object({
+  session: z.string(),
+  window: z.string(),
+  pane: z.string(),
+});
+
+export const SessionListItemSchema = z.object({
+  id: z.string(),
+  source: z.enum(["tmux", "standalone"]),
+  tool: SessionToolSchema,
+  state: SessionStateSchema,
+  summary: z.string(),
+  lastActivity: z.number(),
+  stableForMs: z.number().optional(),
+  hasAttention: z.boolean().optional(),
+  detectionSource: z.string().optional(),
+  parentSessionId: z.string().optional(),
+  project: ProjectInfoSchema.optional(),
+  tmux: TmuxInfoSchema.optional(),
+  currentPath: z.string().optional(),
+  activeTool: z.string().optional(),
+  childCount: z.number().optional(),
+  activeChildCount: z.number().optional(),
+});
+
+export const SessionTreeItemSchema = SessionListItemSchema.extend({
+  children: z.array(SessionListItemSchema),
+});
+
+export const SessionViewCountsSchema = z.object({
+  total: z.number(),
+  visible: z.number(),
+  rootsVisible: z.number(),
+  childrenVisible: z.number(),
+  byState: z.record(z.string(), z.number()),
+  byTool: z.record(z.string(), z.number()),
+});
+
+export const SessionsResponseSchema = z.object({
+  sessions: z.array(SessionTreeItemSchema),
+  counts: SessionViewCountsSchema,
+  generatedAt: z.number(),
+});
+
+export const SessionDetailResponseSchema = z.object({
+  session: z.record(z.string(), z.unknown()).openapi({ description: "Full SessionModel" }),
+});
+
+export const SessionChildrenResponseSchema = z.object({
+  sessionId: z.string(),
+  children: z.array(SessionListItemSchema),
+});
+
+export const SessionMessagesResponseSchema = z.object({
+  sessionId: z.string(),
+  messages: z.array(z.unknown()),
+});

package/src/api/schemas/usage.ts

@@ -0,0 +1,50 @@
+import { z } from "@hono/zod-openapi";
+
+export const UsageWindowSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  usedPercent: z.number().min(0).max(100),
+  used: z.number().optional(),
+  limit: z.number().optional(),
+  windowMinutes: z.number().optional(),
+  resetsAt: z.string().datetime().nullable().optional(),
+  resetInSec: z.number().optional(),
+});
+
+export const ProviderCostSnapshotSchema = z.object({
+  used: z.number(),
+  limit: z.number(),
+  currency: z.string(),
+  period: z.string(),
+  resetsAt: z.string().datetime().nullable().optional(),
+  updatedAt: z.string().datetime(),
+});
+
+export const UsageProviderEntrySchema = z.object({
+  provider: z.string(),
+  accountId: z.string().nullable(),
+  available: z.boolean(),
+  status: z.enum(["ok", "error", "unavailable", "pending"]),
+  metadata: z
+    .object({
+      dataSource: z.string().optional(),
+      accountEmail: z.string().nullable().optional(),
+      accountOrganization: z.string().nullable().optional(),
+      subscriptionType: z.string().nullable().optional(),
+      rateLimitTier: z.string().nullable().optional(),
+      workspaceId: z.string().nullable().optional(),
+      workspaceName: z.string().nullable().optional(),
+    })
+    .optional(),
+  errors: z.array(z.string()).optional(),
+  windows: z.array(UsageWindowSchema).optional(),
+  cost: ProviderCostSnapshotSchema.nullable().optional(),
+  updatedAt: z.string().datetime().optional(),
+});
+
+export const UsageStateSchema = z.object({
+  providers: z.array(UsageProviderEntrySchema),
+  lastRefreshedAt: z.number(),
+});
+
+export const UsageResponseSchema = UsageStateSchema;