@neurocode-ai/plugin 1.18.14 → 1.18.15

package/package.json

@@ -1,54 +1,55 @@
-{
-  "$schema": "https://json.schemastore.org/package.json",
-  "name": "@neurocode-ai/plugin",
-  "version": "1.18.14",
-  "type": "module",
-  "license": "MIT",
-  "scripts": {
-    "typecheck": "tsgo --noEmit",
-    "build": "tsc"
-  },
-  "exports": {
-    ".": "./src/index.ts",
-    "./tool": "./src/tool.ts",
-    "./tui": "./src/tui.ts",
-    "./v2/effect": "./src/v2/effect/index.ts",
-    "./v2/effect/integration": "./src/v2/effect/integration.ts",
-    "./v2/effect/plugin": "./src/v2/effect/plugin.ts",
-    "./v2/promise": "./src/v2/promise/index.ts"
-  },
-  "files": [
-    "dist"
-  ],
-  "dependencies": {
-    "@ai-sdk/provider": "3.0.8",
-    "@neurocode-ai/sdk": "^1.0.0",
-    "effect": "4.0.0-beta.83",
-    "zod": "4.1.8"
-  },
-  "peerDependencies": {
-    "@opentui/core": ">=0.4.5",
-    "@opentui/keymap": ">=0.4.5",
-    "@opentui/solid": ">=0.4.5"
-  },
-  "peerDependenciesMeta": {
-    "@opentui/core": {
-      "optional": true
-    },
-    "@opentui/keymap": {
-      "optional": true
-    },
-    "@opentui/solid": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@opentui/core": "0.4.5",
-    "@opentui/keymap": "0.4.5",
-    "@opentui/solid": "0.4.5",
-    "@tsconfig/node22": "22.0.2",
-    "@types/node": "24.12.2",
-    "typescript": "5.8.2",
-    "@typescript/native-preview": "7.0.0-dev.20251207.1"
-  }
-}
+{
+    "$schema":  "https://json.schemastore.org/package.json",
+    "name":  "@neurocode-ai/plugin",
+    "version":  "1.18.15",
+    "type":  "module",
+    "license":  "MIT",
+    "scripts":  {
+                    "typecheck":  "tsgo --noEmit",
+                    "build":  "tsc"
+                },
+    "exports":  {
+                    ".":  "./src/index.ts",
+                    "./tool":  "./src/tool.ts",
+                    "./tui":  "./src/tui.ts",
+                    "./v2/effect":  "./src/v2/effect/index.ts",
+                    "./v2/effect/integration":  "./src/v2/effect/integration.ts",
+                    "./v2/effect/plugin":  "./src/v2/effect/plugin.ts",
+                    "./v2/promise":  "./src/v2/promise/index.ts"
+                },
+    "files":  [
+                  "src",
+                  "dist"
+              ],
+    "dependencies":  {
+                         "@ai-sdk/provider":  "3.0.8",
+                         "@neurocode-ai/sdk":  "^1.0.0",
+                         "effect":  "4.0.0-beta.83",
+                         "zod":  "4.1.8"
+                     },
+    "peerDependencies":  {
+                             "@opentui/core":  "\u003e=0.4.5",
+                             "@opentui/keymap":  "\u003e=0.4.5",
+                             "@opentui/solid":  "\u003e=0.4.5"
+                         },
+    "peerDependenciesMeta":  {
+                                 "@opentui/core":  {
+                                                       "optional":  true
+                                                   },
+                                 "@opentui/keymap":  {
+                                                         "optional":  true
+                                                     },
+                                 "@opentui/solid":  {
+                                                        "optional":  true
+                                                    }
+                             },
+    "devDependencies":  {
+                            "@opentui/core":  "0.4.5",
+                            "@opentui/keymap":  "0.4.5",
+                            "@opentui/solid":  "0.4.5",
+                            "@tsconfig/node22":  "22.0.2",
+                            "@types/node":  "24.12.2",
+                            "typescript":  "5.8.2",
+                            "@typescript/native-preview":  "7.0.0-dev.20251207.1"
+                        }
+}

package/src/example-workspace.ts

@@ -0,0 +1,34 @@
+import type { Plugin } from "@neurocode-ai/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,335 @@
+import type {
+  Event,
+  createNeurocodeClient,
+  Project,
+  Model,
+  Provider,
+  Permission,
+  UserMessage,
+  Message,
+  Part,
+  Config as SDKConfig,
+} from "@neurocode-ai/sdk"
+import type { Provider as ProviderV2, Model as ModelV2, Auth } from "@neurocode-ai/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 createNeurocodeClient>
+  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
+              metadata?: Record<string, 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; metadata?: Record<string, 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; metadata?: Record<string, 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 {
+  dispose?: () => Promise<void>
+  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>
+  "experimental.provider.small_model"?: (input: { provider: ProviderV2 }, output: { model?: ModelV2 }) => 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,54 @@
+import { z } from "zod"
+
+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): Promise<void>
+}
+
+type AskInput = {
+  permission: string
+  patterns: string[]
+  always: string[]
+  metadata: { [key: string]: any }
+}
+
+export type ToolAttachment = {
+  type: "file"
+  mime: string
+  url: string
+  filename?: string
+}
+
+export type ToolResult =
+  | string
+  | {
+      title?: string
+      output: string
+      metadata?: { [key: string]: any }
+      attachments?: ToolAttachment[]
+    }
+
+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>