@neurocode-ai/core 1.18.8

package/src/tool/websearch.ts

@@ -0,0 +1,260 @@
+export * as WebSearchTool from "./websearch"
+
+import { ToolFailure } from "@neurocode-ai/llm"
+import { Context, Duration, Effect, Layer, Schema } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import { makeLocationNode } from "../effect/app-node"
+import { LayerNodePlatform } from "../effect/app-node-platform"
+import { truthy } from "../flag/flag"
+import { InstallationVersion } from "../installation/version"
+import { PositiveInt } from "../schema"
+import { PermissionV2 } from "../permission"
+import { Tool } from "./tool"
+import { Tools } from "./tools"
+import { collectBoundedResponseBody } from "./http-body"
+import { checksum } from "../util/encode"
+import { ToolRegistry } from "./registry"
+
+export const name = "websearch"
+export const NO_RESULTS = "No search results found. Please try a different query."
+export const EXA_URL = "https://mcp.exa.ai/mcp"
+export const PARALLEL_URL = "https://search.parallel.ai/mcp"
+export const MAX_NUM_RESULTS = 20
+export const MAX_CONTEXT_CHARACTERS = 50_000
+export const MAX_RESPONSE_BYTES = 256 * 1024
+
+/**
+ * Provider-independent local web search retained in V2 core for launch parity.
+ * This invokes the legacy Exa/Parallel product backends itself. It is distinct
+ * from provider-hosted web search tools, which remain route-owned and execute
+ * at the model provider. Ownership of this compromise can be revisited later.
+ */
+export const description = `Search the web using the session's local web search provider. Use this for current information beyond knowledge cutoff.
+
+This is a provider-independent local tool backed by Exa or Parallel. Provider-hosted web search tools are separate and execute at the model provider.
+
+Optional controls support result count, live crawling ('fallback' or 'preferred'), search type ('auto', 'fast', or 'deep'), and maximum context characters.
+
+The current year is ${new Date().getFullYear()}. Use this year when searching for recent information or current events.`
+
+export const Input = Schema.Struct({
+  query: Schema.String.annotate({ description: "Websearch query" }),
+  numResults: Schema.optional(PositiveInt.check(Schema.isLessThanOrEqualTo(MAX_NUM_RESULTS))).annotate({
+    description: `Number of search results to return (default: 8, maximum: ${MAX_NUM_RESULTS})`,
+  }),
+  livecrawl: Schema.optional(Schema.Literals(["fallback", "preferred"])).annotate({
+    description:
+      "Live crawl mode - 'fallback': use live crawling as backup if cached unavailable, 'preferred': prioritize live crawling (default: 'fallback')",
+  }),
+  type: Schema.optional(Schema.Literals(["auto", "fast", "deep"])).annotate({
+    description: "Search type - 'auto': balanced search (default), 'fast': quick results, 'deep': comprehensive search",
+  }),
+  contextMaxCharacters: Schema.optional(PositiveInt.check(Schema.isLessThanOrEqualTo(MAX_CONTEXT_CHARACTERS))).annotate(
+    {
+      description: `Maximum characters for context string optimized for models (default: 10000, maximum: ${MAX_CONTEXT_CHARACTERS})`,
+    },
+  ),
+})
+
+export const Provider = Schema.Literals(["exa", "parallel"])
+export type Provider = typeof Provider.Type
+
+export interface Config {
+  readonly provider?: Provider
+  readonly enableExa: boolean
+  readonly enableParallel: boolean
+  readonly exaApiKey?: string
+  readonly parallelApiKey?: string
+}
+
+export class ConfigService extends Context.Service<ConfigService, Config>()("@neurocode/v2/WebSearchConfig") {}
+
+/** Isolates the retained product environment contract from the generic tool implementation. */
+export const defaultConfigLayer = Layer.sync(ConfigService, () =>
+  ConfigService.of({
+    provider:
+      process.env.NEUROCODE_WEBSEARCH_PROVIDER === "exa" || process.env.NEUROCODE_WEBSEARCH_PROVIDER === "parallel"
+        ? process.env.NEUROCODE_WEBSEARCH_PROVIDER
+        : undefined,
+    enableExa: truthy("NEUROCODE_EXPERIMENTAL") || truthy("NEUROCODE_ENABLE_EXA") || truthy("NEUROCODE_EXPERIMENTAL_EXA"),
+    enableParallel: truthy("NEUROCODE_ENABLE_PARALLEL") || truthy("NEUROCODE_EXPERIMENTAL_PARALLEL"),
+    exaApiKey: process.env.EXA_API_KEY,
+    parallelApiKey: process.env.PARALLEL_API_KEY,
+  }),
+)
+
+export const configNode = makeLocationNode({ service: ConfigService, layer: defaultConfigLayer, deps: [] })
+
+export function selectProvider(
+  sessionID: string,
+  flags: Pick<Config, "enableExa" | "enableParallel"> = { enableExa: false, enableParallel: false },
+  override?: Provider,
+): Provider {
+  if (override) return override
+  if (flags.enableParallel) return "parallel"
+  if (flags.enableExa) return "exa"
+  return Number.parseInt(checksum(sessionID) ?? "0", 36) % 2 === 0 ? "exa" : "parallel"
+}
+
+const McpResult = Schema.Struct({
+  result: Schema.Struct({
+    content: Schema.Array(Schema.Struct({ type: Schema.String, text: Schema.String })),
+  }),
+})
+const decodeMcpResult = Schema.decodeUnknownEffect(Schema.fromJsonString(McpResult))
+
+const parsePayload = (payload: string) =>
+  Effect.gen(function* () {
+    const trimmed = payload.trim()
+    if (!trimmed.startsWith("{")) return undefined
+    return (yield* decodeMcpResult(trimmed)).result.content.find((item) => item.text)?.text
+  })
+
+export const parseResponse = Effect.fn("WebSearchTool.parseResponse")(function* (body: string) {
+  const trimmed = body.trim()
+  const direct = trimmed ? yield* parsePayload(trimmed) : undefined
+  if (direct) return direct
+  for (const line of body.split("\n")) {
+    if (!line.startsWith("data: ")) continue
+    const data = yield* parsePayload(line.substring(6))
+    if (data) return data
+  }
+  return undefined
+})
+
+const ExaArgs = Schema.Struct({
+  query: Schema.String,
+  type: Schema.String,
+  numResults: Schema.Number,
+  livecrawl: Schema.String,
+  contextMaxCharacters: Schema.optional(Schema.Number),
+})
+const ParallelArgs = Schema.Struct({
+  objective: Schema.String,
+  search_queries: Schema.Array(Schema.String),
+  session_id: Schema.String,
+})
+const McpRequest = <F extends Schema.Struct.Fields>(args: Schema.Struct<F>) =>
+  Schema.Struct({
+    jsonrpc: Schema.Literal("2.0"),
+    id: Schema.Literal(1),
+    method: Schema.Literal("tools/call"),
+    params: Schema.Struct({ name: Schema.String, arguments: args }),
+  })
+
+const exaUrl = (apiKey: string | undefined) => {
+  if (!apiKey) return EXA_URL
+  const url = new URL(EXA_URL)
+  url.searchParams.set("exaApiKey", apiKey)
+  return url.toString()
+}
+
+const callMcp = <F extends Schema.Struct.Fields>(
+  http: HttpClient.HttpClient,
+  url: string,
+  tool: string,
+  args: Schema.Struct<F>,
+  value: Schema.Struct.Type<F>,
+  headers: Record<string, string> = {},
+) =>
+  Effect.gen(function* () {
+    const request = yield* HttpClientRequest.post(url).pipe(
+      HttpClientRequest.accept("application/json, text/event-stream"),
+      HttpClientRequest.setHeaders(headers),
+      HttpClientRequest.schemaBodyJson(McpRequest(args))({
+        jsonrpc: "2.0" as const,
+        id: 1 as const,
+        method: "tools/call" as const,
+        params: { name: tool, arguments: value },
+      }),
+    )
+    return yield* Effect.gen(function* () {
+      const response = yield* HttpClient.filterStatusOk(http).execute(request)
+      const body = yield* collectBoundedResponseBody(
+        response,
+        MAX_RESPONSE_BYTES,
+        () => new Error(`${tool} response exceeded ${MAX_RESPONSE_BYTES} bytes`),
+      )
+      return yield* parseResponse(body.toString("utf8"))
+    }).pipe(
+      Effect.timeoutOrElse({
+        duration: Duration.seconds(25),
+        orElse: () => Effect.fail(new Error(`${tool} request timed out`)),
+      }),
+    )
+  })
+
+const Output = Schema.Struct({
+  provider: Provider,
+  text: Schema.String,
+})
+
+const layer = Layer.effectDiscard(
+  Effect.gen(function* () {
+    const tools = yield* Tools.Service
+    const http = yield* HttpClient.HttpClient
+    const config = yield* ConfigService
+    const permission = yield* PermissionV2.Service
+
+    yield* tools
+      .register({
+        [name]: Tool.make({
+          description,
+          input: Input,
+          output: Output,
+          toModelOutput: ({ output }) => [{ type: "text", text: output.text }],
+          execute: (input, context) => {
+            const provider = selectProvider(context.sessionID, config, config.provider)
+            return Effect.gen(function* () {
+              yield* permission.assert({
+                action: name,
+                resources: [input.query],
+                save: ["*"],
+                metadata: { ...input, provider },
+                sessionID: context.sessionID,
+                agent: context.agent,
+                source: { type: "tool", messageID: context.assistantMessageID, callID: context.toolCallID },
+              })
+
+              const text =
+                provider === "exa"
+                  ? yield* callMcp(http, exaUrl(config.exaApiKey), "web_search_exa", ExaArgs, {
+                      query: input.query,
+                      type: input.type || "auto",
+                      numResults: input.numResults || 8,
+                      livecrawl: input.livecrawl || "fallback",
+                      contextMaxCharacters: input.contextMaxCharacters,
+                    })
+                  : yield* callMcp(
+                      http,
+                      PARALLEL_URL,
+                      "web_search",
+                      ParallelArgs,
+                      {
+                        objective: input.query,
+                        search_queries: [input.query],
+                        session_id: context.sessionID,
+                        // V2 invocation context does not safely expose the model yet.
+                      },
+                      {
+                        "User-Agent": `opencode/${InstallationVersion}`,
+                        ...(config.parallelApiKey ? { Authorization: `Bearer ${config.parallelApiKey}` } : {}),
+                      },
+                    )
+              return {
+                provider,
+                text: text ?? NO_RESULTS,
+              }
+            }).pipe(Effect.mapError(() => new ToolFailure({ message: `Unable to search the web for ${input.query}` })))
+          },
+        }),
+      })
+      .pipe(Effect.orDie)
+  }),
+)
+
+export const node = makeLocationNode({
+  name: "tool/websearch",
+  layer,
+  deps: [ToolRegistry.node, PermissionV2.node, LayerNodePlatform.httpClient, configNode],
+})

package/src/tool/write.ts

@@ -0,0 +1,101 @@
+/**
+ * Model-facing V2 file-write leaf. Relative paths resolve within the active
+ * Location. Absolute paths inside that Location are accepted, while explicit
+ * absolute external paths retain mutation capability through a separate
+ * external_directory approval before edit approval.
+ */
+export * as WriteTool from "./write"
+
+import { ToolFailure } from "@neurocode-ai/llm"
+import { Effect, Layer, Schema } from "effect"
+import { makeLocationNode } from "../effect/app-node"
+import { FileMutation } from "../file-mutation"
+import { LocationMutation } from "../location-mutation"
+import { PermissionV2 } from "../permission"
+import { ToolRegistry } from "./registry"
+import { Tool } from "./tool"
+import { Tools } from "./tools"
+
+export const name = "write"
+
+// TODO: Revisit whether model-facing mutation schemas should prefer absolute `filePath` naming for trained-in compatibility after evaluating model behavior.
+export const Input = Schema.Struct({
+  path: Schema.String.annotate({
+    description:
+      "File path to write. Relative paths resolve within the active Location. Absolute paths inside that Location are accepted; external absolute paths require external_directory approval.",
+  }),
+  content: Schema.String.annotate({ description: "Content to write to the file" }),
+})
+
+export const Output = Schema.Struct({
+  operation: Schema.Literal("write"),
+  target: Schema.String,
+  resource: Schema.String,
+  existed: Schema.Boolean,
+})
+export type Output = typeof Output.Type
+
+export const toModelOutput = (output: Output) =>
+  `${output.existed ? "Wrote" : "Created"} file successfully: ${output.resource}`
+
+/** Deferred V2 write UX integrations remain visible at the model-facing seam. */
+// TODO: Add formatter integration after V2 formatter runtime exists.
+// TODO: Publish watcher/file-edit events after V2 watcher integration exists.
+// TODO: Add snapshots / undo after design exists.
+// TODO: Add LSP notification and diagnostics after V2 LSP runtime exists.
+
+const layer = Layer.effectDiscard(
+  Effect.gen(function* () {
+    const tools = yield* Tools.Service
+    const mutation = yield* LocationMutation.Service
+    const files = yield* FileMutation.Service
+    const permission = yield* PermissionV2.Service
+
+    yield* tools
+      .register({
+        [name]: Tool.withPermission(
+          Tool.make({
+            description:
+              "Write content to one file. Relative paths resolve within the active Location. Absolute paths inside the Location are accepted. Explicit external absolute paths require external_directory approval before edit approval.",
+            input: Input,
+            output: Output,
+            toModelOutput: ({ output }) => [{ type: "text", text: toModelOutput(output) }],
+            execute: (input, context) =>
+              Effect.gen(function* () {
+                const source = {
+                  type: "tool" as const,
+                  messageID: context.assistantMessageID,
+                  callID: context.toolCallID,
+                }
+                const target = yield* mutation.resolve({ path: input.path, kind: "file" })
+                const external = target.externalDirectory
+                if (external)
+                  yield* permission.assert({
+                    ...LocationMutation.externalDirectoryPermission(external),
+                    sessionID: context.sessionID,
+                    agent: context.agent,
+                    source,
+                  })
+                yield* permission.assert({
+                  action: "edit",
+                  resources: [target.resource],
+                  save: ["*"],
+                  sessionID: context.sessionID,
+                  agent: context.agent,
+                  source,
+                })
+                return yield* files.writeTextPreservingBom({ target, content: input.content })
+              }).pipe(Effect.mapError(() => new ToolFailure({ message: `Unable to write ${input.path}` }))),
+          }),
+          "edit",
+        ),
+      })
+      .pipe(Effect.orDie)
+  }),
+)
+
+export const node = makeLocationNode({
+  name: "tool/write",
+  layer,
+  deps: [ToolRegistry.node, LocationMutation.node, FileMutation.node, PermissionV2.node],
+})

package/src/tool-output-store.ts

@@ -0,0 +1,211 @@
+export * as ToolOutputStore from "./tool-output-store"
+
+import path from "path"
+import { Context, Duration, Effect, Layer, Option, Schedule, Schema } from "effect"
+import { Config } from "./config"
+import { FSUtil } from "./fs-util"
+import { Global } from "./global"
+import { makeGlobalNode, makeLocationNode } from "./effect/app-node"
+import { SessionSchema } from "./session/schema"
+import { Identifier } from "./util/identifier"
+import type { ToolOutput } from "@neurocode-ai/llm"
+
+export const MAX_LINES = 2_000
+export const MAX_BYTES = 50 * 1024
+export const RETENTION = Duration.days(7)
+
+export const MANAGED_DIRECTORY = "tool-output"
+
+export interface BoundInput {
+  readonly sessionID: SessionSchema.ID
+  readonly toolCallID: string
+  readonly output: ToolOutput
+}
+
+export interface BoundResult {
+  readonly output: ToolOutput
+  readonly outputPaths: ReadonlyArray<string>
+}
+
+export class StorageError extends Schema.TaggedErrorClass<StorageError>()("ToolOutputStore.StorageError", {
+  operation: Schema.Literals(["encode", "write"]),
+  cause: Schema.Defect(),
+}) {
+  override get message() {
+    const detail = this.cause instanceof Error ? this.cause.message : String(this.cause)
+    return `Failed to ${this.operation} tool output${detail ? `: ${detail}` : ""}`
+  }
+}
+
+export type Error = StorageError
+
+export interface Interface {
+  readonly limits: () => Effect.Effect<{ readonly maxLines: number; readonly maxBytes: number }>
+  readonly bound: (input: BoundInput) => Effect.Effect<BoundResult, Error>
+  readonly cleanup: () => Effect.Effect<void>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@neurocode/v2/ToolOutputStore") {}
+
+const takePrefix = (input: string, maximumBytes: number) => {
+  let bytes = 0
+  let content = ""
+  for (const char of input) {
+    const size = Buffer.byteLength(char, "utf-8")
+    if (bytes + size > maximumBytes) break
+    content += char
+    bytes += size
+  }
+  return content
+}
+
+const takeSuffix = (input: string, maximumBytes: number) => {
+  let bytes = 0
+  const content: string[] = []
+  for (const char of Array.from(input).toReversed()) {
+    const size = Buffer.byteLength(char, "utf-8")
+    if (bytes + size > maximumBytes) break
+    content.unshift(char)
+    bytes += size
+  }
+  return content.join("")
+}
+
+const preview = (text: string, maxLines: number, maxBytes: number) => {
+  const lines = text.split("\n")
+  const headLines = Math.ceil(maxLines / 2)
+  const tailLines = Math.floor(maxLines / 2)
+  const sampled =
+    lines.length <= maxLines
+      ? text
+      : [
+          lines.slice(0, headLines).join("\n"),
+          ...(tailLines > 0 ? [lines.slice(lines.length - tailLines).join("\n")] : []),
+        ].join("\n")
+  if (Buffer.byteLength(sampled, "utf-8") <= maxBytes) {
+    return lines.length <= maxLines
+      ? { head: sampled, tail: "" }
+      : {
+          head: lines.slice(0, headLines).join("\n"),
+          tail: tailLines > 0 ? lines.slice(lines.length - tailLines).join("\n") : "",
+        }
+  }
+  const headBytes = Math.ceil(maxBytes / 2)
+  const tailBytes = Math.floor(maxBytes / 2)
+  return { head: takePrefix(sampled, headBytes), tail: takeSuffix(sampled, tailBytes) }
+}
+
+const boundedPreview = (text: string, marker: string, maxLines: number, maxBytes: number) => {
+  const markerOnly = takePrefix(marker, maxBytes).split("\n").slice(0, maxLines).join("\n")
+  const markerBytes = Buffer.byteLength(marker, "utf-8")
+  if (maxLines <= 4 || maxBytes <= markerBytes + 4) return markerOnly
+  const bounded = preview(text, maxLines - 4, maxBytes - markerBytes - 4)
+  return bounded.tail ? `${bounded.head}\n\n${marker}\n\n${bounded.tail}` : `${bounded.head}\n\n${marker}`
+}
+
+const lineCount = (text: string) => {
+  let count = 1
+  for (const char of text) if (char === "\n") count++
+  return count
+}
+
+const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const fs = yield* FSUtil.Service
+    const global = yield* Global.Service
+    const config = yield* Effect.serviceOption(Config.Service)
+    const directory = path.join(global.data, MANAGED_DIRECTORY)
+    const limits = Effect.fn("ToolOutputStore.limits")(function* () {
+      if (Option.isNone(config)) return { maxLines: MAX_LINES, maxBytes: MAX_BYTES }
+      const entries = yield* config.value.entries().pipe(Effect.catch(() => Effect.succeed([] as Config.Entry[])))
+      const configured = Object.assign(
+        {},
+        ...entries.flatMap((entry) => (entry.type === "document" ? [entry.info.tool_output ?? {}] : [])),
+      )
+      return { maxLines: configured.max_lines ?? MAX_LINES, maxBytes: configured.max_bytes ?? MAX_BYTES }
+    })
+
+    const write = Effect.fn("ToolOutputStore.write")(function* (content: string) {
+      const file = path.join(directory, `tool_${Identifier.ascending()}`)
+      yield* fs.ensureDir(directory).pipe(Effect.mapError((cause) => new StorageError({ operation: "write", cause })))
+      yield* fs
+        .writeFileString(file, content, { flag: "wx" })
+        .pipe(Effect.mapError((cause) => new StorageError({ operation: "write", cause })))
+      return file
+    })
+
+    const bound = Effect.fn("ToolOutputStore.bound")(function* (input: BoundInput) {
+      const outputLimits = yield* limits()
+      const media = input.output.content.filter((item) => item.type === "file")
+      const text = input.output.content.filter((item) => item.type === "text")
+      const contextual =
+        input.output.content.length === 0
+          ? yield* Effect.try({
+              try: () => JSON.stringify(input.output.structured, null, 2) ?? String(input.output.structured),
+              catch: (cause) => new StorageError({ operation: "encode", cause }),
+            })
+          : text.map((item) => item.text).join("")
+      if (
+        lineCount(contextual) <= outputLimits.maxLines &&
+        Buffer.byteLength(contextual, "utf-8") <= outputLimits.maxBytes
+      )
+        return {
+          output: input.output,
+          outputPaths: [],
+        }
+
+      const outputPath = yield* write(contextual)
+      const marker = `... output truncated; full content saved to ${outputPath} ...`
+
+      return {
+        output: {
+          structured: input.output.structured,
+          content: [
+            {
+              type: "text" as const,
+              text: boundedPreview(contextual, marker, outputLimits.maxLines, outputLimits.maxBytes),
+            },
+            ...media,
+          ],
+        },
+        outputPaths: [outputPath],
+      }
+    })
+
+    const cleanup = Effect.fn("ToolOutputStore.cleanup")(function* () {
+      const entries = yield* fs.readDirectory(directory).pipe(Effect.catch(() => Effect.succeed([])))
+      const cutoff = Date.now() - Duration.toMillis(RETENTION)
+      for (const entry of entries) {
+        if (!entry.startsWith("tool_")) continue
+        const file = path.join(directory, entry)
+        const info = yield* fs.stat(file).pipe(Effect.catch(() => Effect.void))
+        const modified = info?.mtime.pipe(
+          Option.map((date) => date.getTime()),
+          Option.getOrElse(() => 0),
+        )
+        if (modified !== undefined && modified < cutoff) yield* fs.remove(file).pipe(Effect.catch(() => Effect.void))
+      }
+    })
+
+    return Service.of({ limits, bound, cleanup })
+  }),
+)
+
+export const node = makeLocationNode({ service: Service, layer, deps: [FSUtil.node, Global.node, Config.node] })
+
+export const nodeWithoutConfig = makeLocationNode({ service: Service, layer, deps: [FSUtil.node, Global.node] })
+
+/** Runs retention scanning once globally rather than once per active Location. */
+export const cleanupLayer = Layer.effectDiscard(
+  Effect.gen(function* () {
+    const store = yield* Service
+    yield* store.cleanup().pipe(Effect.repeat(Schedule.spaced(Duration.hours(1))), Effect.forkScoped)
+  }),
+)
+
+export const cleanupNode = makeGlobalNode({
+  name: "tool-output-cleanup",
+  layer: Layer.merge(layer, cleanupLayer.pipe(Layer.provide(layer))),
+  deps: [FSUtil.node, Global.node],
+})

package/src/util/array.ts

@@ -0,0 +1,10 @@
+export function findLast<T>(
+  items: readonly T[],
+  predicate: (item: T, index: number, items: readonly T[]) => boolean,
+): T | undefined {
+  for (let i = items.length - 1; i >= 0; i -= 1) {
+    const item = items[i]
+    if (predicate(item, i, items)) return item
+  }
+  return undefined
+}

package/src/util/binary.ts

@@ -0,0 +1,41 @@
+export namespace Binary {
+  export function search<T>(array: T[], id: string, compare: (item: T) => string): { found: boolean; index: number } {
+    let left = 0
+    let right = array.length - 1
+
+    while (left <= right) {
+      const mid = Math.floor((left + right) / 2)
+      const midId = compare(array[mid])
+
+      if (midId === id) {
+        return { found: true, index: mid }
+      } else if (midId < id) {
+        left = mid + 1
+      } else {
+        right = mid - 1
+      }
+    }
+
+    return { found: false, index: left }
+  }
+
+  export function insert<T>(array: T[], item: T, compare: (item: T) => string): T[] {
+    const id = compare(item)
+    let left = 0
+    let right = array.length
+
+    while (left < right) {
+      const mid = Math.floor((left + right) / 2)
+      const midId = compare(array[mid])
+
+      if (midId < id) {
+        left = mid + 1
+      } else {
+        right = mid
+      }
+    }
+
+    array.splice(left, 0, item)
+    return array
+  }
+}