saeeol 1.2.0 → 1.2.2

package/src/tool/core/external-directory.ts

@@ -0,0 +1,55 @@
+import path from "path"
+import { Effect } from "effect"
+import * as EffectLogger from "@saeeol/core/effect/logger"
+import { InstanceState } from "@/effect/instance-state"
+import type * as Tool from "./tool"
+import { AppFileSystem } from "@saeeol/core/filesystem"
+
+type Kind = "file" | "directory"
+
+type Options = {
+  bypass?: boolean
+  kind?: Kind
+}
+function root(dir: string) {
+  return path.parse(dir).root === dir
+}
+
+function inside(dir: string, file: string) {
+  return !root(dir) && AppFileSystem.contains(dir, file)
+}
+
+export const assertExternalDirectoryEffect = Effect.fn("Tool.assertExternalDirectory")(function* (
+  ctx: Tool.Context,
+  target?: string,
+  options?: Options,
+) {
+  if (!target) return
+
+  if (options?.bypass) return
+
+  const ins = yield* InstanceState.context
+  const full = process.platform === "win32" ? AppFileSystem.normalizePath(target) : target
+  if (inside(ins.directory, full) || inside(ins.worktree, full)) return
+
+  const kind = options?.kind ?? "file"
+  const dir = kind === "directory" ? full : path.dirname(full)
+  const glob =
+    process.platform === "win32"
+      ? AppFileSystem.normalizePathPattern(path.join(dir, "*"))
+      : path.join(dir, "*").replaceAll("\\", "/")
+
+  yield* ctx.ask({
+    permission: "external_directory",
+    patterns: [glob],
+    always: [glob],
+    metadata: {
+      filepath: full,
+      parentDir: dir,
+    },
+  })
+})
+
+export async function assertExternalDirectory(ctx: Tool.Context, target?: string, options?: Options) {
+  return Effect.runPromise(assertExternalDirectoryEffect(ctx, target, options).pipe(Effect.provide(EffectLogger.layer)))
+}

package/src/tool/core/invalid.ts

@@ -0,0 +1,21 @@
+import { Effect, Schema } from "effect"
+import * as Tool from "./tool"
+
+export const Parameters = Schema.Struct({
+  tool: Schema.String,
+  error: Schema.String,
+})
+
+export const InvalidTool = Tool.define(
+  "invalid",
+  Effect.succeed({
+    description: "Do not use",
+    parameters: Parameters,
+    execute: (params: { tool: string; error: string }) =>
+      Effect.succeed({
+        title: "Invalid Tool",
+        output: `The arguments provided to the tool are invalid: ${params.error}`,
+        metadata: {},
+      }),
+  }),
+)

package/src/tool/core/recall.ts

@@ -0,0 +1,164 @@
+import { Effect, Schema } from "effect"
+import * as Tool from "./tool"
+import { Instance } from "../../project/instance"
+import { Locale } from "../../util/locale"
+import { Filesystem } from "../../util/filesystem" 
+import { WorktreeFamily } from "../../overlay/worktree-family" 
+import DESCRIPTION from "./recall.txt"
+
+const Parameters = Schema.Struct({
+  mode: Schema.Literals(["search", "read"]).annotate({
+    description: "'search' to find sessions by title, 'read' to get a session transcript",
+  }),
+  query: Schema.optional(Schema.String).annotate({
+    description: "Search query to match against session titles (required for search mode)",
+  }),
+  sessionID: Schema.optional(Schema.String).annotate({
+    description: "Session ID to read the transcript of (required for read mode)",
+  }),
+  limit: Schema.optional(Schema.Number).annotate({
+    description: "Maximum number of search results to return (default: 20, max: 50)",
+  }),
+})
+
+export const RecallTool = Tool.define(
+  "saeeol_local_recall",
+  Effect.gen(function* () {
+    return {
+      description: DESCRIPTION,
+      parameters: Parameters,
+      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) =>
+        Effect.gen(function* () {
+          if (params.mode === "search") {
+            return yield* Effect.promise(() => search(params, ctx))
+          }
+          return yield* Effect.promise(() => read(params, ctx))
+        }).pipe(Effect.orDie),
+    }
+  }),
+)
+
+async function search(params: { query?: string; limit?: number }, ctx: Tool.Context) {
+  if (!params.query) {
+    throw new Error("The 'query' parameter is required when mode is 'search'")
+  }
+
+  await ctx.ask({
+    permission: "recall",
+    patterns: ["search"],
+    always: ["search"],
+    metadata: {
+      mode: "search",
+      query: params.query,
+    },
+  })
+
+  const limit = Math.min(params.limit ?? 20, 50)
+  const dirs = await WorktreeFamily.list() 
+  const { Session } = await import("../../session/session") 
+
+  const results: Array<{
+    id: string
+    title: string
+    directory: string
+    updated: string
+  }> = []
+
+  for (const session of Session.listGlobal({
+    projectID: Instance.project.id, 
+    directories: dirs, 
+    search: params.query,
+    roots: true,
+    limit,
+  })) {
+    results.push({
+      id: session.id,
+      title: session.title,
+      directory: session.directory,
+      updated: Locale.todayTimeOrDateTime(session.time.updated),
+    })
+  }
+
+  if (results.length === 0) {
+    return {
+      title: `Search: "${params.query}" (no results)`,
+      output: `No sessions found matching "${params.query}".`,
+      metadata: {},
+    }
+  }
+
+  const lines = results.map((r) => `- **${r.title}**\n  ID: ${r.id} | Updated: ${r.updated} | Dir: ${r.directory}`)
+
+  return {
+    title: `Search: "${params.query}" (${results.length} results)`,
+    output: lines.join("\n"),
+    metadata: {},
+  }
+}
+
+async function read(params: { sessionID?: string }, ctx: Tool.Context) {
+  if (!params.sessionID) {
+    throw new Error("The 'sessionID' parameter is required when mode is 'read'")
+  }
+
+  const { Session } = await import("../../session/session") 
+  const { SessionID } = await import("../../session/schema") 
+  const session = await Session.get(SessionID.make(params.sessionID)).catch(() => {
+    throw new Error(`Session "${params.sessionID}" not found. Use search mode first to find valid session IDs.`)
+  })
+  const dirs = await WorktreeFamily.list() 
+  const dir = Filesystem.resolve(session.directory)
+  if (!dirs.some((root) => Filesystem.contains(root, dir))) {
+    throw new Error(
+      `Session "${params.sessionID}" belongs to a different workspace and cannot be read from this directory.`,
+    )
+  }
+
+  const cross = session.projectID !== Instance.project.id
+  if (cross) {
+    await ctx.ask({
+      permission: "recall",
+      patterns: [session.directory],
+      always: [session.directory],
+      metadata: {
+        sessionID: session.id,
+        title: session.title,
+        directory: session.directory,
+      },
+    })
+  }
+
+  const msgs = await Session.messages({ sessionID: session.id })
+  const lines: string[] = [
+    `# Session: ${session.title}`,
+    `Directory: ${session.directory}`,
+    `Created: ${Locale.todayTimeOrDateTime(session.time.created)}`,
+    "",
+  ]
+
+  for (const msg of msgs) {
+    if (msg.info.role === "user") {
+      lines.push("## User")
+      for (const part of msg.parts) {
+        if (part.type === "text") lines.push(part.text)
+      }
+      lines.push("")
+    }
+    if (msg.info.role === "assistant") {
+      lines.push("## Assistant")
+      for (const part of msg.parts) {
+        if (part.type === "text") lines.push(part.text)
+        if (part.type === "tool" && part.state.status === "completed") {
+          lines.push(`[Tool: ${part.tool}] ${part.state.title}`)
+        }
+      }
+      lines.push("")
+    }
+  }
+
+  return {
+    title: `Read: ${session.title}`,
+    output: lines.join("\n"),
+    metadata: {},
+  }
+}

package/src/tool/core/recall.txt

@@ -0,0 +1,12 @@
+Search and read past conversations from the current project on this machine, including its git worktrees. Use this to recall previous work, find how something was implemented before, or retrieve context from another worktree in the same repo.
+
+Two modes:
+1. **Search** - Find sessions by title keyword in the current project and its worktrees. Returns a list of matching sessions with their title, directory, and last updated time. Use this first to locate relevant conversations.
+2. **Read** - Retrieve the full transcript of a specific session by ID. Returns the conversation messages (user prompts and assistant responses) so you can understand what was discussed and done.
+
+Usage notes:
+  - Search matches against session titles using case-insensitive substring matching
+  - Results are limited to the current project/worktree family
+  - Reading a session from a different project is rejected
+  - Use search mode first to find session IDs, then read mode to get the full conversation
+  - Session transcripts can be large; prefer searching first to narrow down which session to read

package/src/tool/core/schema.ts

@@ -0,0 +1,16 @@
+import { Schema } from "effect"
+
+import { Identifier } from "@/id/id"
+import { zod, ZodOverride } from "@/util/effect-zod"
+import { withStatics } from "@/util/schema"
+
+const toolIdSchema = Schema.String.annotate({ [ZodOverride]: Identifier.schema("tool") }).pipe(Schema.brand("ToolID"))
+
+export type ToolID = typeof toolIdSchema.Type
+
+export const ToolID = toolIdSchema.pipe(
+  withStatics((schema: typeof toolIdSchema) => ({
+    ascending: (id?: string) => schema.make(Identifier.ascending("tool", id)),
+    zod: zod(schema),
+  })),
+)

package/src/tool/core/tool.ts

@@ -0,0 +1,162 @@
+import { Effect, Schema } from "effect"
+import type { MessageV2 } from "../../session/message-v2"
+import type { Permission } from "../../permission"
+import type { SessionID, MessageID } from "../../session/schema"
+import * as Truncate from "./truncate"
+import { Agent } from "@/agent/agent"
+
+interface Metadata {
+  [key: string]: any
+}
+
+// TODO: remove this hack
+export type DynamicDescription = (agent: Agent.Info) => Effect.Effect<string>
+
+export type Context<M extends Metadata = Metadata> = {
+  sessionID: SessionID
+  messageID: MessageID
+  agent: string
+  abort: AbortSignal
+  callID?: string
+  extra?: { [key: string]: unknown }
+  messages: MessageV2.WithParts[]
+  metadata(input: { title?: string; metadata?: M }): Effect.Effect<void>
+  ask(input: Omit<Permission.Request, "id" | "sessionID" | "tool">): Effect.Effect<void>
+}
+
+export interface ExecuteResult<M extends Metadata = Metadata> {
+  title: string
+  metadata: M
+  output: string
+  attachments?: Omit<MessageV2.FilePart, "id" | "sessionID" | "messageID">[]
+}
+
+export interface Def<
+  Parameters extends Schema.Decoder<unknown> = Schema.Decoder<unknown>,
+  M extends Metadata = Metadata,
+> {
+  id: string
+  description: string
+  parameters: Parameters
+  execute(args: Schema.Schema.Type<Parameters>, ctx: Context): Effect.Effect<ExecuteResult<M>>
+  formatValidationError?(error: unknown): string
+}
+export type DefWithoutID<
+  Parameters extends Schema.Decoder<unknown> = Schema.Decoder<unknown>,
+  M extends Metadata = Metadata,
+> = Omit<Def<Parameters, M>, "id">
+
+export interface Info<
+  Parameters extends Schema.Decoder<unknown> = Schema.Decoder<unknown>,
+  M extends Metadata = Metadata,
+> {
+  id: string
+  init: () => Effect.Effect<DefWithoutID<Parameters, M>>
+}
+
+type Init<Parameters extends Schema.Decoder<unknown>, M extends Metadata> =
+  | DefWithoutID<Parameters, M>
+  | (() => Effect.Effect<DefWithoutID<Parameters, M>>)
+
+export type InferParameters<T> =
+  T extends Info<infer P, any>
+    ? Schema.Schema.Type<P>
+    : T extends Effect.Effect<Info<infer P, any>, any, any>
+      ? Schema.Schema.Type<P>
+      : never
+export type InferMetadata<T> =
+  T extends Info<any, infer M> ? M : T extends Effect.Effect<Info<any, infer M>, any, any> ? M : never
+
+export type InferDef<T> =
+  T extends Info<infer P, infer M>
+    ? Def<P, M>
+    : T extends Effect.Effect<Info<infer P, infer M>, any, any>
+      ? Def<P, M>
+      : never
+
+function wrap<Parameters extends Schema.Decoder<unknown>, Result extends Metadata>(
+  id: string,
+  init: Init<Parameters, Result>,
+  truncate: Truncate.Interface,
+  agents: Agent.Interface,
+) {
+  return () =>
+    Effect.gen(function* () {
+      const toolInfo = typeof init === "function" ? { ...(yield* init()) } : { ...init }
+      // Compile the parser closure once per tool init; `decodeUnknownEffect`
+      // allocates a new closure per call, so hoisting avoids re-closing it for
+      // every LLM tool invocation.
+      const decode = Schema.decodeUnknownEffect(toolInfo.parameters)
+      const execute = toolInfo.execute
+      toolInfo.execute = (args, ctx) => {
+        const attrs = {
+          "tool.name": id,
+          "session.id": ctx.sessionID,
+          "message.id": ctx.messageID,
+          ...(ctx.callID ? { "tool.call_id": ctx.callID } : {}),
+        }
+        return Effect.gen(function* () {
+          const decoded = yield* decode(args).pipe(
+            Effect.mapError((error) =>
+              toolInfo.formatValidationError
+                ? new Error(toolInfo.formatValidationError(error), { cause: error })
+                : new Error(
+                    `The ${id} tool was called with invalid arguments: ${error}.\nPlease rewrite the input so it satisfies the expected schema.`,
+                    { cause: error },
+                  ),
+            ),
+          )
+          const result = yield* execute(decoded as Schema.Schema.Type<Parameters>, ctx)
+          if (result.metadata.truncated !== undefined) {
+            return result
+          }
+          const agent = yield* agents.get(ctx.agent)
+          const truncated = yield* truncate.output(result.output, {}, agent)
+          return {
+            ...result,
+            output: truncated.content,
+            metadata: {
+              ...result.metadata,
+              truncated: truncated.truncated,
+              ...(truncated.truncated && { outputPath: truncated.outputPath }),
+            },
+          }
+        }).pipe(Effect.orDie, Effect.withSpan("Tool.execute", { attributes: attrs }))
+      }
+      return toolInfo
+    })
+}
+
+export function define<
+  Parameters extends Schema.Decoder<unknown>,
+  Result extends Metadata,
+  R,
+  ID extends string = string,
+>(
+  id: ID,
+  init: Effect.Effect<Init<Parameters, Result>, never, R>,
+): Effect.Effect<Info<Parameters, Result>, never, R | Truncate.Service | Agent.Service> & { id: ID } {
+  return Object.assign(
+    Effect.gen(function* () {
+      const resolved = yield* init
+      const truncate = yield* Truncate.Service
+      const agents = yield* Agent.Service
+      return { id, init: wrap(id, resolved, truncate, agents) }
+    }),
+    { id },
+  )
+}
+
+export function init<P extends Schema.Decoder<unknown>, M extends Metadata>(
+  info: Info<P, M>,
+): Effect.Effect<Def<P, M>> {
+  return Effect.gen(function* () {
+    const init = yield* info.init()
+    return {
+      ...init,
+      id: info.id,
+    }
+  })
+}
+
+export * as Tool from "./tool"

package/src/tool/core/truncate.ts

@@ -0,0 +1,160 @@
+import { NodePath } from "@effect/platform-node"
+import { Cause, Duration, Effect, Layer, Option, Schedule, Context } from "effect"
+import path from "path"
+import type { Agent } from "../../agent/agent"
+import { AppFileSystem } from "@saeeol/core/filesystem"
+import { evaluate } from "@/permission/evaluate"
+import { Config } from "@/config/config"
+import { Identifier } from "../../id/id"
+import * as Log from "@saeeol/core/util/log"
+import { ToolID } from "./schema"
+import { TRUNCATION_DIR } from "./truncation-dir"
+
+const log = Log.create({ service: "truncation" })
+const RETENTION = Duration.days(7)
+
+export const MAX_LINES = 2000
+export const MAX_BYTES = 50 * 1024
+export const DIR = TRUNCATION_DIR
+export const GLOB = path.join(TRUNCATION_DIR, "*")
+
+export type Result = { content: string; truncated: false } | { content: string; truncated: true; outputPath: string }
+
+export interface Options {
+  maxLines?: number
+  maxBytes?: number
+  direction?: "head" | "tail"
+}
+
+function hasTaskTool(agent?: Agent.Info) {
+  if (!agent?.permission) return false
+  return evaluate("task", "*", agent.permission).action !== "deny"
+}
+
+export interface Interface {
+  readonly cleanup: () => Effect.Effect<void>
+  readonly write: (text: string) => Effect.Effect<string>
+  /**
+   * Returns output unchanged when it fits within the limits, otherwise writes the full text
+   * to the truncation directory and returns a preview plus a hint to inspect the saved file.
+   */
+  readonly output: (text: string, options?: Options, agent?: Agent.Info) => Effect.Effect<Result>
+  /**
+   * Resolved truncation limits: values from `tool_output` in saeeol config, or MAX_LINES / MAX_BYTES if unset.
+   */
+  readonly limits: () => Effect.Effect<{ maxLines: number; maxBytes: number }>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@saeeol/Truncate") {}
+
+export const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const fs = yield* AppFileSystem.Service
+
+    const cleanup = Effect.fn("Truncate.cleanup")(function* () {
+      const cutoff = Identifier.timestamp(
+        Identifier.create("tool", "ascending", Date.now() - Duration.toMillis(RETENTION)),
+      )
+      const entries = yield* fs.readDirectory(TRUNCATION_DIR).pipe(
+        Effect.map((all) => all.filter((name) => name.startsWith("tool_"))),
+        Effect.catch(() => Effect.succeed([])),
+      )
+      for (const entry of entries) {
+        if (Identifier.timestamp(entry) >= cutoff) continue
+        yield* fs.remove(path.join(TRUNCATION_DIR, entry)).pipe(Effect.catch(() => Effect.void))
+      }
+    })
+
+    const write = Effect.fn("Truncate.write")(function* (text: string) {
+      const file = path.join(TRUNCATION_DIR, ToolID.ascending())
+      yield* fs.ensureDir(TRUNCATION_DIR).pipe(Effect.orDie)
+      yield* fs.writeFileString(file, text).pipe(Effect.orDie)
+      return file
+    })
+
+    const limits = Effect.fn("Truncate.limits")(function* () {
+      const configSvc = yield* Effect.serviceOption(Config.Service)
+      if (Option.isNone(configSvc)) return { maxLines: MAX_LINES, maxBytes: MAX_BYTES }
+      const cfg = yield* configSvc.value.get().pipe(Effect.catch(() => Effect.succeed(undefined)))
+      return {
+        maxLines: cfg?.tool_output?.max_lines ?? MAX_LINES,
+        maxBytes: cfg?.tool_output?.max_bytes ?? MAX_BYTES,
+      }
+    })
+
+    const output = Effect.fn("Truncate.output")(function* (text: string, options: Options = {}, agent?: Agent.Info) {
+      const resolved = yield* limits()
+      const maxLines = options.maxLines ?? resolved.maxLines
+      const maxBytes = options.maxBytes ?? resolved.maxBytes
+      const direction = options.direction ?? "head"
+      const lines = text.split("\n")
+      const totalBytes = Buffer.byteLength(text, "utf-8")
+
+      if (lines.length <= maxLines && totalBytes <= maxBytes) {
+        return { content: text, truncated: false } as const
+      }
+
+      const out: string[] = []
+      let i = 0
+      let bytes = 0
+      let hitBytes = false
+
+      if (direction === "head") {
+        for (i = 0; i < lines.length && i < maxLines; i++) {
+          const size = Buffer.byteLength(lines[i], "utf-8") + (i > 0 ? 1 : 0)
+          if (bytes + size > maxBytes) {
+            hitBytes = true
+            break
+          }
+          out.push(lines[i])
+          bytes += size
+        }
+      } else {
+        for (i = lines.length - 1; i >= 0 && out.length < maxLines; i--) {
+          const size = Buffer.byteLength(lines[i], "utf-8") + (out.length > 0 ? 1 : 0)
+          if (bytes + size > maxBytes) {
+            hitBytes = true
+            break
+          }
+          out.unshift(lines[i])
+          bytes += size
+        }
+      }
+
+      const removed = hitBytes ? totalBytes - bytes : lines.length - out.length
+      const unit = hitBytes ? "bytes" : "lines"
+      const preview = out.join("\n")
+      const file = yield* write(text)
+
+      const hint = hasTaskTool(agent)
+        ? `The tool call succeeded but the output was truncated. Full output saved to: ${file}\nUse the Task tool to have explore agent process this file with Grep and Read (with offset/limit). Do NOT read the full file yourself - delegate to save context.`
+        : `The tool call succeeded but the output was truncated. Full output saved to: ${file}\nUse Grep to search the full content or Read with offset/limit to view specific sections.`
+
+      return {
+        content:
+          direction === "head"
+            ? `${preview}\n\n...${removed} ${unit} truncated...\n\n${hint}`
+            : `...${removed} ${unit} truncated...\n\n${hint}\n\n${preview}`,
+        truncated: true,
+        outputPath: file,
+      } as const
+    })
+
+    yield* cleanup().pipe(
+      Effect.catchCause((cause) => {
+        log.error("truncation cleanup failed", { cause: Cause.pretty(cause) })
+        return Effect.void
+      }),
+      Effect.repeat(Schedule.spaced(Duration.hours(1))),
+      Effect.delay(Duration.minutes(1)),
+      Effect.forkScoped,
+    )
+
+    return Service.of({ cleanup, write, output, limits })
+  }),
+)
+
+export const defaultLayer = layer.pipe(Layer.provide(AppFileSystem.defaultLayer), Layer.provide(NodePath.layer))
+
+export * as Truncate from "./truncate"

package/src/tool/core/truncation-dir.ts

@@ -0,0 +1,4 @@
+import path from "path"
+import { Global } from "@saeeol/core/global"
+
+export const TRUNCATION_DIR = path.join(Global.Path.data, "tool-output")

package/src/tool/diagnostics.ts

@@ -1,20 +1 @@
-import type { LSPClient } from "@/lsp/client"
-
-/**
- * Filter diagnostics to only include entries for the specified files.
- * Tools like edit, write, and apply_patch receive diagnostics for ALL project files
- * from the LSP, but only the edited files' diagnostics are relevant for storage
- * and display. Storing all files' diagnostics bloats session payloads significantly
- * (100KB+ per tool call in large projects).
- */
-export function filterDiagnostics(
-  diagnostics: Record<string, LSPClient.Diagnostic[]>,
-  files: string[],
-): Record<string, LSPClient.Diagnostic[]> {
-  const result: Record<string, LSPClient.Diagnostic[]> = {}
-  for (const file of files) {
-    const items = diagnostics[file]
-    if (items) result[file] = items
-  }
-  return result
-}
+export * from "./integration/diagnostics"