@saeeol/plugin 7.3.2 → 7.3.4

package/package.json

@@ -1,53 +1,50 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@saeeol/plugin",
-  "version": "7.3.2",
+  "version": "7.3.4",
   "type": "module",
   "license": "Apache-2.0",
-  "publishConfig": {
-  "access": "public",
-  "registry": "https://registry.npmjs.org"
-},
-"scripts": {
-  "typecheck": "tsgo --noEmit",
-  "build": "tsc"
-},
-"exports": {
-  ".": "./src/index.ts",
-  "./tool": "./src/tool.ts",
-  "./tui": "./src/tui.ts"
-},
-"files": [
-  "dist"
-],
-"dependencies": {
-  "@saeeol/sdk": "7.3.1",
-  "effect": "4.0.0-beta.57",
-  "zod": "4.1.8"
-},
-"peerDependencies": {
-  "@opentui/core": ">=0.2.2",
-  "@opentui/solid": ">=0.2.2"
-},
-"peerDependenciesMeta": {
-  "@opentui/core": {
-    "optional": true
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org" },
+  "scripts": {
+    "typecheck": "tsgo --noEmit",
+    "build": "tsc"
   },
-  "@opentui/solid": {
-    "optional": true
+  "exports": {
+    ".": "./src/index.ts",
+    "./tool": "./src/tool.ts",
+    "./tui": "./src/tui.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@saeeol/sdk": "7.3.3",
+    "effect": "4.0.0-beta.57",
+    "zod": "4.1.8"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.2.2",
+    "@opentui/solid": ">=0.2.2"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@opentui/core": "0.2.2",
+    "@opentui/solid": "0.2.2",
+    "@tsconfig/node22": "22.0.2",
+    "@types/node": "22.13.9",
+    "typescript": "5.8.2",
+    "@typescript/native-preview": "7.0.0-dev.20260316.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SAEEOL/saeeol",
+    "directory": "packages/plugin"
   }
-},
-"devDependencies": {
-  "@opentui/core": "0.2.2",
-  "@opentui/solid": "0.2.2",
-  "@tsconfig/node22": "22.0.2",
-  "@types/node": "22.13.9",
-  "typescript": "5.8.2",
-  "@typescript/native-preview": "7.0.0-dev.20260316.1"
-},
-"repository": {
-  "type": "git",
-  "url": "https://github.com/SAEEOL/saeeol",
-  "directory": "packages/plugin"
-}
 }

package/src/example-workspace.ts

@@ -0,0 +1,34 @@
+import type { Plugin } from "@saeeol/plugin"
+import { mkdir, rm } from "node:fs/promises"
+
+export const FolderWorkspacePlugin: Plugin = async ({ experimental_workspace }) => {
+  experimental_workspace.register("folder", {
+    name: "Folder",
+    description: "Create a blank folder",
+    configure(config) {
+      const rand = "" + Math.random()
+
+      return {
+        ...config,
+        directory: `/tmp/folder/folder-${rand}`,
+      }
+    },
+    async create(config) {
+      if (!config.directory) return
+      await mkdir(config.directory, { recursive: true })
+    },
+    async remove(config) {
+      await rm(config.directory!, { recursive: true, force: true })
+    },
+    target(config) {
+      return {
+        type: "local",
+        directory: config.directory!,
+      }
+    },
+  })
+
+  return {}
+}
+
+export default FolderWorkspacePlugin

package/src/example.ts

@@ -0,0 +1,18 @@
+import { Plugin } from "./index.js"
+import { tool } from "./tool.js"
+
+export const ExamplePlugin: Plugin = async (_ctx) => {
+  return {
+    tool: {
+      mytool: tool({
+        description: "This is a custom tool",
+        args: {
+          foo: tool.schema.string().describe("foo"),
+        },
+        async execute(args) {
+          return `Hello ${args.foo}!`
+        },
+      }),
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,333 @@
+import type {
+  Event,
+  createSaeeolClient,
+  Project,
+  Model,
+  Provider,
+  Permission,
+  UserMessage,
+  Message,
+  Part,
+  Auth,
+  Config as SDKConfig,
+} from "@saeeol/sdk"
+import type { Provider as ProviderV2, Model as ModelV2 } from "@saeeol/sdk/v2"
+
+import type { BunShell } from "./shell.js"
+import { type ToolDefinition } from "./tool.js"
+
+export * from "./tool.js"
+
+export type ProviderContext = {
+  source: "env" | "config" | "custom" | "api"
+  info: Provider
+  options: Record<string, any>
+}
+
+export type WorkspaceInfo = {
+  id: string
+  type: string
+  name: string
+  branch: string | null
+  directory: string | null
+  extra: unknown | null
+  projectID: string
+}
+
+export type WorkspaceTarget =
+  | {
+      type: "local"
+      directory: string
+    }
+  | {
+      type: "remote"
+      url: string | URL
+      headers?: HeadersInit
+    }
+
+export type WorkspaceAdapter = {
+  name: string
+  description: string
+  configure(config: WorkspaceInfo): WorkspaceInfo | Promise<WorkspaceInfo>
+  create(config: WorkspaceInfo, env: Record<string, string | undefined>, from?: WorkspaceInfo): Promise<void>
+  remove(config: WorkspaceInfo): Promise<void>
+  target(config: WorkspaceInfo): WorkspaceTarget | Promise<WorkspaceTarget>
+}
+
+export type PluginInput = {
+  client: ReturnType<typeof createSaeeolClient>
+  project: Project
+  directory: string
+  worktree: string
+  experimental_workspace: {
+    register(type: string, adapter: WorkspaceAdapter): void
+  }
+  serverUrl: URL
+  $: BunShell
+}
+
+export type PluginOptions = Record<string, unknown>
+
+export type Config = Omit<SDKConfig, "plugin"> & {
+  plugin?: Array<string | [string, PluginOptions]>
+}
+
+export type Plugin = (input: PluginInput, options?: PluginOptions) => Promise<Hooks>
+
+export type PluginModule = {
+  id?: string
+  server: Plugin
+  tui?: never
+}
+
+type Rule = {
+  key: string
+  op: "eq" | "neq"
+  value: string
+}
+
+export type AuthHook = {
+  provider: string
+  loader?: (auth: () => Promise<Auth>, provider: Provider) => Promise<Record<string, any>>
+  methods: (
+    | {
+        type: "oauth"
+        label: string
+        prompts?: Array<
+          | {
+              type: "text"
+              key: string
+              message: string
+              placeholder?: string
+              validate?: (value: string) => string | undefined
+              /** @deprecated Use `when` instead */
+              condition?: (inputs: Record<string, string>) => boolean
+              when?: Rule
+            }
+          | {
+              type: "select"
+              key: string
+              message: string
+              options: Array<{
+                label: string
+                value: string
+                hint?: string
+              }>
+              /** @deprecated Use `when` instead */
+              condition?: (inputs: Record<string, string>) => boolean
+              when?: Rule
+            }
+        >
+        authorize(inputs?: Record<string, string>): Promise<AuthOAuthResult>
+      }
+    | {
+        type: "api"
+        label: string
+        prompts?: Array<
+          | {
+              type: "text"
+              key: string
+              message: string
+              placeholder?: string
+              validate?: (value: string) => string | undefined
+              /** @deprecated Use `when` instead */
+              condition?: (inputs: Record<string, string>) => boolean
+              when?: Rule
+            }
+          | {
+              type: "select"
+              key: string
+              message: string
+              options: Array<{
+                label: string
+                value: string
+                hint?: string
+              }>
+              /** @deprecated Use `when` instead */
+              condition?: (inputs: Record<string, string>) => boolean
+              when?: Rule
+            }
+        >
+        authorize?(inputs?: Record<string, string>): Promise<
+          | {
+              type: "success"
+              key: string
+              provider?: string
+            }
+          | {
+              type: "failed"
+            }
+        >
+      }
+  )[]
+}
+
+export type AuthOAuthResult = { url: string; instructions: string } & (
+  | {
+      method: "auto"
+      callback(): Promise<
+        | ({
+            type: "success"
+            provider?: string
+          } & (
+            | {
+                refresh: string
+                access: string
+                expires: number
+                accountId?: string
+                enterpriseUrl?: string
+              }
+            | { key: string }
+          ))
+        | {
+            type: "failed"
+          }
+      >
+    }
+  | {
+      method: "code"
+      callback(code: string): Promise<
+        | ({
+            type: "success"
+            provider?: string
+          } & (
+            | {
+                refresh: string
+                access: string
+                expires: number
+                accountId?: string
+                enterpriseUrl?: string
+              }
+            | { key: string }
+          ))
+        | {
+            type: "failed"
+          }
+      >
+    }
+)
+
+export type ProviderHookContext = {
+  auth?: Auth
+}
+
+export type ProviderHook = {
+  id: string
+  models?: (provider: ProviderV2, ctx: ProviderHookContext) => Promise<Record<string, ModelV2>>
+}
+
+/** @deprecated Use AuthOAuthResult instead. */
+export type AuthOuathResult = AuthOAuthResult
+
+export interface Hooks {
+  event?: (input: { event: Event }) => Promise<void>
+  config?: (input: Config) => Promise<void>
+  tool?: {
+    [key: string]: ToolDefinition
+  }
+  auth?: AuthHook
+  provider?: ProviderHook
+  /**
+   * Called when a new message is received
+   */
+  "chat.message"?: (
+    input: {
+      sessionID: string
+      agent?: string
+      model?: { providerID: string; modelID: string }
+      messageID?: string
+      variant?: string
+    },
+    output: { message: UserMessage; parts: Part[] },
+  ) => Promise<void>
+  /**
+   * Modify parameters sent to LLM
+   */
+  "chat.params"?: (
+    input: { sessionID: string; agent: string; model: Model; provider: ProviderContext; message: UserMessage },
+    output: {
+      temperature: number
+      topP: number
+      topK: number
+      maxOutputTokens: number | undefined
+      options: Record<string, any>
+    },
+  ) => Promise<void>
+  "chat.headers"?: (
+    input: { sessionID: string; agent: string; model: Model; provider: ProviderContext; message: UserMessage },
+    output: { headers: Record<string, string> },
+  ) => Promise<void>
+  "permission.ask"?: (input: Permission, output: { status: "ask" | "deny" | "allow" }) => Promise<void>
+  "command.execute.before"?: (
+    input: { command: string; sessionID: string; arguments: string },
+    output: { parts: Part[] },
+  ) => Promise<void>
+  "tool.execute.before"?: (
+    input: { tool: string; sessionID: string; callID: string },
+    output: { args: any },
+  ) => Promise<void>
+  "shell.env"?: (
+    input: { cwd: string; sessionID?: string; callID?: string },
+    output: { env: Record<string, string> },
+  ) => Promise<void>
+  "tool.execute.after"?: (
+    input: { tool: string; sessionID: string; callID: string; args: any },
+    output: {
+      title: string
+      output: string
+      metadata: any
+    },
+  ) => Promise<void>
+  "experimental.chat.messages.transform"?: (
+    input: {},
+    output: {
+      messages: {
+        info: Message
+        parts: Part[]
+      }[]
+    },
+  ) => Promise<void>
+  "experimental.chat.system.transform"?: (
+    input: { sessionID?: string; model: Model },
+    output: {
+      system: string[]
+    },
+  ) => Promise<void>
+  /**
+   * Called before session compaction starts. Allows plugins to customize
+   * the compaction prompt.
+   *
+   * - `context`: Additional context strings appended to the default prompt
+   * - `prompt`: If set, replaces the default compaction prompt entirely
+   */
+  "experimental.session.compacting"?: (
+    input: { sessionID: string },
+    output: { context: string[]; prompt?: string },
+  ) => Promise<void>
+  /**
+   * Called after compaction succeeds and before a synthetic user
+   * auto-continue message is added.
+   *
+   * - `enabled`: Defaults to `true`. Set to `false` to skip the synthetic
+   *   user "continue" turn.
+   */
+  "experimental.compaction.autocontinue"?: (
+    input: {
+      sessionID: string
+      agent: string
+      model: Model
+      provider: ProviderContext
+      message: UserMessage
+      overflow: boolean
+    },
+    output: { enabled: boolean },
+  ) => Promise<void>
+  "experimental.text.complete"?: (
+    input: { sessionID: string; messageID: string; partID: string },
+    output: { text: string },
+  ) => Promise<void>
+  /**
+   * Modify tool definitions (description and parameters) sent to LLM
+   */
+  "tool.definition"?: (input: { toolID: string }, output: { description: string; parameters: any }) => Promise<void>
+}

package/src/shell.ts

@@ -0,0 +1,136 @@
+export type ShellFunction = (input: Uint8Array) => Uint8Array
+
+export type ShellExpression =
+  | { toString(): string }
+  | Array<ShellExpression>
+  | string
+  | { raw: string }
+  | ReadableStream
+
+export interface BunShell {
+  (strings: TemplateStringsArray, ...expressions: ShellExpression[]): BunShellPromise
+
+  /**
+   * Perform bash-like brace expansion on the given pattern.
+   * @param pattern - Brace pattern to expand
+   */
+  braces(pattern: string): string[]
+
+  /**
+   * Escape strings for input into shell commands.
+   */
+  escape(input: string): string
+
+  /**
+   * Change the default environment variables for shells created by this instance.
+   */
+  env(newEnv?: Record<string, string | undefined>): BunShell
+
+  /**
+   * Default working directory to use for shells created by this instance.
+   */
+  cwd(newCwd?: string): BunShell
+
+  /**
+   * Configure the shell to not throw an exception on non-zero exit codes.
+   */
+  nothrow(): BunShell
+
+  /**
+   * Configure whether or not the shell should throw an exception on non-zero exit codes.
+   */
+  throws(shouldThrow: boolean): BunShell
+}
+
+export interface BunShellPromise extends Promise<BunShellOutput> {
+  readonly stdin: WritableStream
+
+  /**
+   * Change the current working directory of the shell.
+   */
+  cwd(newCwd: string): this
+
+  /**
+   * Set environment variables for the shell.
+   */
+  env(newEnv: Record<string, string> | undefined): this
+
+  /**
+   * By default, the shell will write to the current process's stdout and stderr, as well as buffering that output.
+   * This configures the shell to only buffer the output.
+   */
+  quiet(): this
+
+  /**
+   * Read from stdout as a string, line by line
+   * Automatically calls quiet() to disable echoing to stdout.
+   */
+  lines(): AsyncIterable<string>
+
+  /**
+   * Read from stdout as a string.
+   * Automatically calls quiet() to disable echoing to stdout.
+   */
+  text(encoding?: BufferEncoding): Promise<string>
+
+  /**
+   * Read from stdout as a JSON object
+   * Automatically calls quiet()
+   */
+  json(): Promise<any>
+
+  /**
+   * Read from stdout as an ArrayBuffer
+   * Automatically calls quiet()
+   */
+  arrayBuffer(): Promise<ArrayBuffer>
+
+  /**
+   * Read from stdout as a Blob
+   * Automatically calls quiet()
+   */
+  blob(): Promise<Blob>
+
+  /**
+   * Configure the shell to not throw an exception on non-zero exit codes.
+   */
+  nothrow(): this
+
+  /**
+   * Configure whether or not the shell should throw an exception on non-zero exit codes.
+   */
+  throws(shouldThrow: boolean): this
+}
+
+export interface BunShellOutput {
+  readonly stdout: Buffer
+  readonly stderr: Buffer
+  readonly exitCode: number
+
+  /**
+   * Read from stdout as a string
+   */
+  text(encoding?: BufferEncoding): string
+
+  /**
+   * Read from stdout as a JSON object
+   */
+  json(): any
+
+  /**
+   * Read from stdout as an ArrayBuffer
+   */
+  arrayBuffer(): ArrayBuffer
+
+  /**
+   * Read from stdout as an Uint8Array
+   */
+  bytes(): Uint8Array
+
+  /**
+   * Read from stdout as a Blob
+   */
+  blob(): Blob
+}
+
+export type BunShellError = Error & BunShellOutput

package/src/tool.ts

@@ -0,0 +1,41 @@
+import { z } from "zod"
+import { Effect } from "effect"
+
+export type ToolContext = {
+  sessionID: string
+  messageID: string
+  agent: string
+  /**
+   * Current project directory for this session.
+   * Prefer this over process.cwd() when resolving relative paths.
+   */
+  directory: string
+  /**
+   * Project worktree root for this session.
+   * Useful for generating stable relative paths (e.g. path.relative(worktree, absPath)).
+   */
+  worktree: string
+  abort: AbortSignal
+  metadata(input: { title?: string; metadata?: { [key: string]: any } }): void
+  ask(input: AskInput): Effect.Effect<void>
+}
+
+type AskInput = {
+  permission: string
+  patterns: string[]
+  always: string[]
+  metadata: { [key: string]: any }
+}
+
+export type ToolResult = string | { output: string; metadata?: { [key: string]: any } }
+
+export function tool<Args extends z.ZodRawShape>(input: {
+  description: string
+  args: Args
+  execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<ToolResult>
+}) {
+  return input
+}
+tool.schema = z
+
+export type ToolDefinition = ReturnType<typeof tool>