saeeol 1.1.0 → 1.1.1

package/src/server/routes/instance/experimental-mcp.ts

@@ -0,0 +1,215 @@
+import { Hono } from "hono"
+import { describeRoute, validator, resolver } from "hono-openapi"
+import z from "zod"
+import * as EffectZod from "@/util/effect-zod"
+import { ProviderID, ModelID } from "@/provider/schema"
+import { ToolRegistry } from "@/tool/registry"
+import { Agent } from "@/agent/agent"
+import { MCP } from "@/mcp"
+import { Session } from "@/session/session"
+import { Instance } from "@/project/instance"
+import { WorktreeFamily } from "@/saeeol/worktree-family"
+import { Filesystem } from "@/util/filesystem"
+import path from "path"
+import { Effect } from "effect"
+import { lazy } from "@/util/lazy"
+import { jsonRequest, runRequest } from "./trace"
+import { errors } from "../../error"
+
+const QueryBoolean = z.union([
+  z.preprocess((value) => (value === "true" ? true : value === "false" ? false : value), z.boolean()),
+  z.enum(["true", "false"]),
+])
+
+function queryBoolean(value: z.infer<typeof QueryBoolean> | undefined) {
+  if (value === undefined) return
+  return value === true || value === "true"
+}
+
+export const MCPRoutes = lazy(() =>
+  new Hono()
+    .get(
+      "/tool/ids",
+      describeRoute({
+        summary: "List tool IDs",
+        description:
+          "Get a list of all available tool IDs, including both built-in tools and dynamically registered tools.",
+        operationId: "tool.ids",
+        responses: {
+          200: {
+            description: "Tool IDs",
+            content: {
+              "application/json": {
+                schema: resolver(z.array(z.string()).meta({ ref: "ToolIDs" })),
+              },
+            },
+          },
+          ...errors(400),
+        },
+      }),
+      async (c) =>
+        jsonRequest("ExperimentalRoutes.tool.ids", c, function* () {
+          const registry = yield* ToolRegistry.Service
+          return yield* registry.ids()
+        }),
+    )
+    .get(
+      "/tool",
+      describeRoute({
+        summary: "List tools",
+        description:
+          "Get a list of available tools with their JSON schema parameters for a specific provider and model combination.",
+        operationId: "tool.list",
+        responses: {
+          200: {
+            description: "Tools",
+            content: {
+              "application/json": {
+                schema: resolver(
+                  z
+                    .array(
+                      z
+                        .object({
+                          id: z.string(),
+                          description: z.string(),
+                          parameters: z.any(),
+                        })
+                        .meta({ ref: "ToolListItem" }),
+                    )
+                    .meta({ ref: "ToolList" }),
+                ),
+              },
+            },
+          },
+          ...errors(400),
+        },
+      }),
+      validator(
+        "query",
+        z.object({
+          provider: z.string(),
+          model: z.string(),
+        }),
+      ),
+      async (c) => {
+        const { provider, model } = c.req.valid("query")
+        const tools = await runRequest(
+          "ExperimentalRoutes.tool.list",
+          c,
+          Effect.gen(function* () {
+            const agents = yield* Agent.Service
+            const registry = yield* ToolRegistry.Service
+            return yield* registry.tools({
+              providerID: ProviderID.make(provider),
+              modelID: ModelID.make(model),
+              agent: yield* agents.get(yield* agents.defaultAgent()),
+            })
+          }),
+        )
+        return c.json(
+          tools.map((t) => ({
+            id: t.id,
+            description: t.description,
+            parameters: EffectZod.toJsonSchema(t.parameters),
+          })),
+        )
+      },
+    )
+    .get(
+      "/session",
+      describeRoute({
+        summary: "List sessions",
+        description:
+          "Get a list of all Saeeol sessions across projects, sorted by most recently updated. Archived sessions are excluded by default.",
+        operationId: "experimental.session.list",
+        responses: {
+          200: {
+            description: "List of sessions",
+            content: {
+              "application/json": {
+                schema: resolver(Session.GlobalInfo.zod.array()),
+              },
+            },
+          },
+        },
+      }),
+      validator(
+        "query",
+        z.object({
+          projectID: z.string().optional().meta({ description: "Filter sessions by project ID" }),
+          directory: z.string().optional().meta({ description: "Filter sessions by project directory" }),
+          worktrees: z.coerce
+            .boolean()
+            .optional()
+            .meta({ description: "Restrict sessions to the current repo worktree family or current directory" }),
+          roots: QueryBoolean.optional().meta({ description: "Only return root sessions (no parentID)" }),
+          start: z.coerce
+            .number()
+            .optional()
+            .meta({ description: "Filter sessions updated on or after this timestamp (milliseconds since epoch)" }),
+          cursor: z.coerce
+            .number()
+            .optional()
+            .meta({ description: "Return sessions updated before this timestamp (milliseconds since epoch)" }),
+          search: z.string().optional().meta({ description: "Filter sessions by title (case-insensitive)" }),
+          limit: z.coerce.number().optional().meta({ description: "Maximum number of sessions to return" }),
+          archived: QueryBoolean.optional().meta({ description: "Include archived sessions (default false)" }),
+        }),
+      ),
+      async (c) => {
+        const query = c.req.valid("query")
+        const limit = query.limit ?? 100
+        const projectID = query.worktrees && !query.projectID ? Instance.project.id : query.projectID
+        const directories = query.worktrees ? await WorktreeFamily.list() : undefined
+        const sorted = directories ? [...directories].sort((a, b) => b.length - a.length) : undefined
+        const sessions: Session.GlobalInfo[] = []
+        for await (const session of Session.listGlobal({
+          projectID,
+          directory: query.worktrees ? undefined : query.directory,
+          directories,
+          roots: queryBoolean(query.roots),
+          start: query.start,
+          cursor: query.cursor,
+          search: query.search,
+          limit: limit + 1,
+          archived: queryBoolean(query.archived),
+        })) {
+          if (sorted) {
+            const root = sorted.find((d) => Filesystem.contains(d, session.directory))
+            sessions.push({ ...session, worktreeName: path.basename(root ?? session.directory) })
+            continue
+          }
+          sessions.push(session)
+        }
+        const hasMore = sessions.length > limit
+        const list = hasMore ? sessions.slice(0, limit) : sessions
+        if (hasMore && list.length > 0) {
+          c.header("x-next-cursor", String(list[list.length - 1].time.updated))
+        }
+        return c.json(list)
+      },
+    )
+    .get(
+      "/resource",
+      describeRoute({
+        summary: "Get MCP resources",
+        description: "Get all available MCP resources from connected servers. Optionally filter by name.",
+        operationId: "experimental.resource.list",
+        responses: {
+          200: {
+            description: "MCP resources",
+            content: {
+              "application/json": {
+                schema: resolver(z.record(z.string(), MCP.Resource.zod)),
+              },
+            },
+          },
+        },
+      }),
+      async (c) =>
+        jsonRequest("ExperimentalRoutes.resource.list", c, function* () {
+          const mcp = yield* MCP.Service
+          return yield* mcp.resources()
+        }),
+    )
+)

package/src/server/routes/instance/experimental-review.ts

@@ -0,0 +1,232 @@
+import { Hono } from "hono"
+import { describeRoute, validator, resolver } from "hono-openapi"
+import z from "zod"
+import { Worktree } from "@/worktree"
+import { Instance } from "@/project/instance"
+import { Project } from "@/project/project"
+import { Review } from "@/saeeol/review/review"
+import { WorktreeDiff } from "@/saeeol/review/worktree-diff"
+import * as Log from "@saeeol/core/util/log"
+import { Snapshot } from "@/snapshot"
+import { lazy } from "@/util/lazy"
+import { jsonRequest } from "./trace"
+import { errors } from "../../error"
+
+export const ReviewRoutes = lazy(() =>
+  new Hono()
+    .post(
+      "/worktree",
+      describeRoute({
+        summary: "Create worktree",
+        description: "Create a new git worktree for the current project and run any configured startup scripts.",
+        operationId: "worktree.create",
+        responses: {
+          200: {
+            description: "Worktree created",
+            content: {
+              "application/json": {
+                schema: resolver(Worktree.Info.zod),
+              },
+            },
+          },
+          ...errors(400),
+        },
+      }),
+      validator("json", Worktree.CreateInput.zod.optional()),
+      async (c) =>
+        jsonRequest("ExperimentalRoutes.worktree.create", c, function* () {
+          const body = c.req.valid("json")
+          const svc = yield* Worktree.Service
+          return yield* svc.create(body)
+        }),
+    )
+    .get(
+      "/worktree",
+      describeRoute({
+        summary: "List worktrees",
+        description: "List all sandbox worktrees for the current project.",
+        operationId: "worktree.list",
+        responses: {
+          200: {
+            description: "List of worktree directories",
+            content: {
+              "application/json": {
+                schema: resolver(z.array(z.string())),
+              },
+            },
+          },
+        },
+      }),
+      async (c) =>
+        jsonRequest("ExperimentalRoutes.worktree.list", c, function* () {
+          const svc = yield* Project.Service
+          return yield* svc.sandboxes(Instance.project.id)
+        }),
+    )
+    .delete(
+      "/worktree",
+      describeRoute({
+        summary: "Remove worktree",
+        description: "Remove a git worktree and delete its branch.",
+        operationId: "worktree.remove",
+        responses: {
+          200: {
+            description: "Worktree removed",
+            content: {
+              "application/json": {
+                schema: resolver(z.boolean()),
+              },
+            },
+          },
+          ...errors(400),
+        },
+      }),
+      validator("json", Worktree.RemoveInput.zod),
+      async (c) =>
+        jsonRequest("ExperimentalRoutes.worktree.remove", c, function* () {
+          const body = c.req.valid("json")
+          const worktree = yield* Worktree.Service
+          const project = yield* Project.Service
+          yield* worktree.remove(body)
+          yield* project.removeSandbox(Instance.project.id, body.directory)
+          return true
+        }),
+    )
+    .post(
+      "/worktree/reset",
+      describeRoute({
+        summary: "Reset worktree",
+        description: "Reset a worktree branch to the primary default branch.",
+        operationId: "worktree.reset",
+        responses: {
+          200: {
+            description: "Worktree reset",
+            content: {
+              "application/json": {
+                schema: resolver(z.boolean()),
+              },
+            },
+          },
+          ...errors(400),
+        },
+      }),
+      validator("json", Worktree.ResetInput.zod),
+      async (c) =>
+        jsonRequest("ExperimentalRoutes.worktree.reset", c, function* () {
+          const body = c.req.valid("json")
+          const svc = yield* Worktree.Service
+          yield* svc.reset(body)
+          return true
+        }),
+    )
+    .get(
+      "/worktree/diff",
+      describeRoute({
+        summary: "Get worktree diff",
+        description: "Get file diffs for a worktree compared to its base branch. Includes uncommitted changes.",
+        operationId: "worktree.diff",
+        responses: {
+          200: {
+            description: "File diffs",
+            content: {
+              "application/json": {
+                schema: resolver(z.array(Snapshot.FileDiff.zod)),
+              },
+            },
+          },
+          ...errors(400),
+        },
+      }),
+      validator(
+        "query",
+        z.object({
+          base: z.string().optional().meta({ description: "Base branch or ref to diff against" }),
+        }),
+      ),
+      async (c) => {
+        const log = Log.create({ service: "worktree-diff" })
+        const query = c.req.valid("query")
+        const base = query.base || (await Review.getBaseBranch())
+        const dir = Instance.directory
+        log.info("computing diff", { dir, base })
+        const diffs = await WorktreeDiff.full({ dir, base, log })
+        return c.json(
+          diffs.map((diff) => ({
+            file: diff.file,
+            before: diff.before,
+            after: diff.after,
+            additions: diff.additions,
+            deletions: diff.deletions,
+            status: diff.status,
+          })),
+        )
+      },
+    )
+    .get(
+      "/worktree/diff/summary",
+      describeRoute({
+        summary: "Get worktree diff summary",
+        description: "Get lightweight file diff metadata for a worktree compared to its base branch.",
+        operationId: "worktree.diffSummary",
+        responses: {
+          200: {
+            description: "Diff summary items",
+            content: {
+              "application/json": {
+                schema: resolver(z.array(WorktreeDiff.Item.zod)),
+              },
+            },
+          },
+          ...errors(400),
+        },
+      }),
+      validator(
+        "query",
+        z.object({
+          base: z.string().optional().meta({ description: "Base branch or ref to diff against" }),
+        }),
+      ),
+      async (c) => {
+        const log = Log.create({ service: "worktree-diff" })
+        const query = c.req.valid("query")
+        const base = query.base || (await Review.getBaseBranch())
+        const dir = Instance.directory
+        log.info("computing diff summary", { dir, base })
+        return c.json(await WorktreeDiff.summary({ dir, base, log }))
+      },
+    )
+    .get(
+      "/worktree/diff/file",
+      describeRoute({
+        summary: "Get worktree diff detail",
+        description: "Get full diff contents for one worktree file compared to its base branch.",
+        operationId: "worktree.diffFile",
+        responses: {
+          200: {
+            description: "Diff detail item",
+            content: {
+              "application/json": {
+                schema: resolver(WorktreeDiff.Item.zod.nullable()),
+              },
+            },
+          },
+          ...errors(400),
+        },
+      }),
+      validator(
+        "query",
+        z.object({
+          base: z.string().optional().meta({ description: "Base branch or ref to diff against" }),
+          file: z.string().meta({ description: "Relative file path to load diff contents for" }),
+        }),
+      ),
+      async (c) => {
+        const log = Log.create({ service: "worktree-diff" })
+        const query = c.req.valid("query")
+        const base = query.base || (await Review.getBaseBranch())
+        const dir = Instance.directory
+        log.info("computing diff detail", { dir, base, file: query.file })
+        return c.json((await WorktreeDiff.detail({ dir, base, file: query.file, log })) ?? null)
+      },
+    )
+)

package/src/server/routes/instance/experimental.ts

@@ -0,0 +1,12 @@
+import { Hono } from "hono"
+import { lazy } from "@/util/lazy"
+import { ConsoleRoutes } from "./experimental-console"
+import { ReviewRoutes } from "./experimental-review"
+import { MCPRoutes } from "./experimental-mcp"
+
+export const ExperimentalRoutes = lazy(() =>
+  new Hono()
+    .route("/", ConsoleRoutes())
+    .route("/", ReviewRoutes())
+    .route("/", MCPRoutes())
+)

package/src/server/routes/instance/file.ts

@@ -0,0 +1,190 @@
+import { Hono } from "hono"
+import { describeRoute, validator, resolver } from "hono-openapi"
+import z from "zod"
+import { File } from "@/file"
+import { Ripgrep } from "@/file/ripgrep"
+import { LSP } from "@/lsp/lsp"
+import { Instance } from "@/project/instance"
+import { lazy } from "@/util/lazy"
+import { jsonRequest } from "./trace"
+
+export const FileRoutes = lazy(() =>
+  new Hono()
+    .get(
+      "/find",
+      describeRoute({
+        summary: "Find text",
+        description: "Search for text patterns across files in the project using ripgrep.",
+        operationId: "find.text",
+        responses: {
+          200: {
+            description: "Matches",
+            content: {
+              "application/json": {
+                schema: resolver(Ripgrep.SearchMatch.zod.array()),
+              },
+            },
+          },
+        },
+      }),
+      validator(
+        "query",
+        z.object({
+          pattern: z.string(),
+        }),
+      ),
+      async (c) =>
+        jsonRequest("FileRoutes.findText", c, function* () {
+          const pattern = c.req.valid("query").pattern
+          const svc = yield* Ripgrep.Service
+          const result = yield* svc.search({ cwd: Instance.directory, pattern, limit: 10 })
+          return result.items
+        }),
+    )
+    .get(
+      "/find/file",
+      describeRoute({
+        summary: "Find files",
+        description: "Search for files or directories by name or pattern in the project directory.",
+        operationId: "find.files",
+        responses: {
+          200: {
+            description: "File paths",
+            content: {
+              "application/json": {
+                schema: resolver(z.string().array()),
+              },
+            },
+          },
+        },
+      }),
+      validator(
+        "query",
+        z.object({
+          query: z.string(),
+          dirs: z.enum(["true", "false"]).optional(),
+          type: z.enum(["file", "directory"]).optional(),
+          limit: z.coerce.number().int().min(1).max(200).optional(),
+        }),
+      ),
+      async (c) =>
+        jsonRequest("FileRoutes.findFile", c, function* () {
+          const query = c.req.valid("query")
+          const svc = yield* File.Service
+          return yield* svc.search({
+            query: query.query,
+            limit: query.limit ?? 10,
+            dirs: query.dirs !== "false",
+            type: query.type,
+          })
+        }),
+    )
+    .get(
+      "/find/symbol",
+      describeRoute({
+        summary: "Find symbols",
+        description: "Search for workspace symbols like functions, classes, and variables using LSP.",
+        operationId: "find.symbols",
+        responses: {
+          200: {
+            description: "Symbols",
+            content: {
+              "application/json": {
+                schema: resolver(LSP.Symbol.zod.array()),
+              },
+            },
+          },
+        },
+      }),
+      validator(
+        "query",
+        z.object({
+          query: z.string(),
+        }),
+      ),
+      async (c) => {
+        return c.json([])
+      },
+    )
+    .get(
+      "/file",
+      describeRoute({
+        summary: "List files",
+        description: "List files and directories in a specified path.",
+        operationId: "file.list",
+        responses: {
+          200: {
+            description: "Files and directories",
+            content: {
+              "application/json": {
+                schema: resolver(File.Node.zod.array()),
+              },
+            },
+          },
+        },
+      }),
+      validator(
+        "query",
+        z.object({
+          path: z.string(),
+        }),
+      ),
+      async (c) =>
+        jsonRequest("FileRoutes.list", c, function* () {
+          const svc = yield* File.Service
+          return yield* svc.list(c.req.valid("query").path)
+        }),
+    )
+    .get(
+      "/file/content",
+      describeRoute({
+        summary: "Read file",
+        description: "Read the content of a specified file.",
+        operationId: "file.read",
+        responses: {
+          200: {
+            description: "File content",
+            content: {
+              "application/json": {
+                schema: resolver(File.Content.zod),
+              },
+            },
+          },
+        },
+      }),
+      validator(
+        "query",
+        z.object({
+          path: z.string(),
+        }),
+      ),
+      async (c) =>
+        jsonRequest("FileRoutes.read", c, function* () {
+          const svc = yield* File.Service
+          return yield* svc.read(c.req.valid("query").path)
+        }),
+    )
+    .get(
+      "/file/status",
+      describeRoute({
+        summary: "Get file status",
+        description: "Get the git status of all files in the project.",
+        operationId: "file.status",
+        responses: {
+          200: {
+            description: "File status",
+            content: {
+              "application/json": {
+                schema: resolver(File.Info.zod.array()),
+              },
+            },
+          },
+        },
+      }),
+      async (c) =>
+        jsonRequest("FileRoutes.status", c, function* () {
+          const svc = yield* File.Service
+          return yield* svc.status()
+        }),
+    ),
+)

package/src/server/routes/instance/httpapi/AGENTS.md

@@ -0,0 +1,35 @@
+# HttpApi Route Patterns
+
+Use `HttpApiBuilder.group(...)` for normal HTTP endpoints, including streaming HTTP responses such as server-sent events. Handlers should yield stable services once while building the handler layer, then close over those services in endpoint implementations.
+
+```ts
+export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session", (handlers) =>
+  Effect.gen(function* () {
+    const session = yield* Session.Service
+
+    return handlers.handle("list", () => session.list())
+  }),
+)
+```
+
+For SSE endpoints, stay in `HttpApiBuilder.group(...)` and return `HttpServerResponse.stream(...)` from the handler. Annotate the endpoint success schema with `HttpApiSchema.asText({ contentType: "text/event-stream" })` so OpenAPI documents the stream content type.
+
+Use raw `HttpRouter.use(...)` only for routes that do not fit the request/response HttpApi model, such as WebSocket upgrade routes or catch-all fallback routes. Yield stable services at route-layer construction and close over them in `router.add(...)` callbacks.
+
+```ts
+export const rawRoute = HttpRouter.use((router) =>
+  Effect.gen(function* () {
+    const pty = yield* Pty.Service
+
+    yield* router.add("GET", PtyPaths.connect, (request) => connectPty(request, pty))
+  }),
+)
+```
+
+Avoid `Effect.provide(SomeLayer)` inside request handlers or raw route callbacks. Stable layers should be provided once at the application/layer boundary, not rebuilt or scoped per request.
+
+Avoid `HttpRouter.provideRequest(...)` unless the dependency is intentionally request-level. Prefer `HttpRouter.use(...)` for stable app services.
+
+Use `Effect.provideService(...)` in middleware only for request-derived context, such as `WorkspaceRouteContext`, `InstanceRef`, or `WorkspaceRef`. Do not use it to smuggle stable services through request effects when they can be yielded at layer construction.
+
+When adding middleware, compose it at the layer boundary and keep the route tree explicit in `server.ts`. Shared router middleware such as auth, workspace routing, and instance context should stay visible where routes are assembled.