@neurocode-ai/core 1.18.8

package/src/tool/skill.ts

@@ -0,0 +1,109 @@
+export * as SkillTool from "./skill"
+
+import path from "path"
+import { ToolFailure } from "@neurocode-ai/llm"
+import { Effect, Layer, Schema } from "effect"
+import { makeLocationNode } from "../effect/app-node"
+import { FSUtil } from "../fs-util"
+import { SkillV2 } from "../skill"
+import { PermissionV2 } from "../permission"
+import { ToolRegistry } from "./registry"
+import { Tool } from "./tool"
+import { Tools } from "./tools"
+
+export const name = "skill"
+const FILE_LIMIT = 10
+
+export const Input = Schema.Struct({
+  name: Schema.String.annotate({ description: "The name of the skill from the available skills list" }),
+})
+
+export const Output = Schema.Struct({
+  name: Schema.String,
+  directory: Schema.String,
+  output: Schema.String,
+})
+
+export const description = [
+  "Load a specialized skill when the task at hand matches one of the available skills in the system context.",
+  "",
+  "Use this tool to inject the skill's instructions and resources into the current conversation. The output may contain detailed workflow guidance as well as references to scripts, files, etc. in the same directory as the skill.",
+  "",
+  "The skill name must match one of the available skills in the system context.",
+].join("\n")
+
+export const toModelOutput = (skill: SkillV2.Info, files: ReadonlyArray<string>) => {
+  const directory = path.dirname(skill.location)
+  return [
+    `<skill_content name="${skill.name}">`,
+    `# Skill: ${skill.name}`,
+    "",
+    skill.content.trim(),
+    "",
+    `Base directory for this skill: ${directory}`,
+    "Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory.",
+    "Note: file list is sampled.",
+    "",
+    "<skill_files>",
+    ...files.map((file) => `<file>${file}</file>`),
+    "</skill_files>",
+    "</skill_content>",
+  ].join("\n")
+}
+
+const unableToLoad = (name: string, error?: unknown) =>
+  new ToolFailure({ message: `Unable to load skill ${name}`, error })
+
+const layer = Layer.effectDiscard(
+  Effect.gen(function* () {
+    const tools = yield* Tools.Service
+    const fs = yield* FSUtil.Service
+    const skills = yield* SkillV2.Service
+    const permission = yield* PermissionV2.Service
+    yield* tools
+      .register({
+        [name]: Tool.make({
+          description,
+          input: Input,
+          output: Output,
+          toModelOutput: ({ output }) => [{ type: "text", text: output.output }],
+          execute: (input, context) =>
+            Effect.gen(function* () {
+              const current = yield* skills.list()
+              const skill = current.find((skill) => skill.name === input.name)
+              if (!skill) return yield* unableToLoad(input.name)
+              return yield* Effect.gen(function* () {
+                yield* permission.assert({
+                  action: name,
+                  resources: [skill.name],
+                  save: [skill.name],
+                  sessionID: context.sessionID,
+                  agent: context.agent,
+                  source: { type: "tool", messageID: context.assistantMessageID, callID: context.toolCallID },
+                })
+                const directory = path.dirname(skill.location)
+                const files =
+                  path.basename(skill.location) === "SKILL.md"
+                    ? (yield* fs.glob("**/*", { cwd: directory, absolute: true, include: "file", dot: true }))
+                        .filter((file) => path.basename(file) !== "SKILL.md")
+                        .toSorted()
+                        .slice(0, FILE_LIMIT)
+                    : []
+                return {
+                  name: skill.name,
+                  directory,
+                  output: toModelOutput(skill, files),
+                }
+              }).pipe(Effect.mapError((error) => unableToLoad(input.name, error)))
+            }),
+        }),
+      })
+      .pipe(Effect.orDie)
+  }),
+)
+
+export const node = makeLocationNode({
+  name: "tool/skill",
+  layer,
+  deps: [ToolRegistry.node, FSUtil.node, SkillV2.node, PermissionV2.node],
+})

package/src/tool/todowrite.ts

@@ -0,0 +1,62 @@
+export * as TodoWriteTool from "./todowrite"
+
+import { ToolFailure } from "@neurocode-ai/llm"
+import { Effect, Layer, Schema } from "effect"
+import { makeLocationNode } from "../effect/app-node"
+import { PermissionV2 } from "../permission"
+import { SessionTodo } from "../session/todo"
+import { ToolRegistry } from "./registry"
+import { Tool } from "./tool"
+import { Tools } from "./tools"
+
+export const name = "todowrite"
+
+export const Input = Schema.Struct({
+  todos: Schema.Array(SessionTodo.Info).annotate({ description: "The updated todo list" }),
+})
+
+export const Output = Schema.Struct({
+  todos: Schema.Array(SessionTodo.Info),
+})
+export type Output = typeof Output.Type
+
+export const toModelOutput = (output: Output) => JSON.stringify(output.todos, null, 2)
+
+const layer = Layer.effectDiscard(
+  Effect.gen(function* () {
+    const tools = yield* Tools.Service
+    const todos = yield* SessionTodo.Service
+    const permission = yield* PermissionV2.Service
+
+    yield* tools
+      .register({
+        [name]: Tool.make({
+          description:
+            "Create and maintain a structured task list for the current coding session. Use it to track progress during multi-step work and keep todo statuses current.",
+          input: Input,
+          output: Output,
+          toModelOutput: ({ output }) => [{ type: "text", text: toModelOutput(output) }],
+          execute: (input, context) =>
+            Effect.gen(function* () {
+              yield* permission.assert({
+                action: name,
+                resources: ["*"],
+                save: ["*"],
+                sessionID: context.sessionID,
+                agent: context.agent,
+                source: { type: "tool", messageID: context.assistantMessageID, callID: context.toolCallID },
+              })
+              yield* todos.update({ sessionID: context.sessionID, todos: input.todos })
+              return { todos: input.todos }
+            }).pipe(Effect.mapError(() => new ToolFailure({ message: "Unable to update todos" }))),
+        }),
+      })
+      .pipe(Effect.orDie)
+  }),
+)
+
+export const node = makeLocationNode({
+  name: "tool/todowrite",
+  layer,
+  deps: [ToolRegistry.node, PermissionV2.node, SessionTodo.node],
+})

package/src/tool/tool.ts

@@ -0,0 +1,162 @@
+export * as Tool from "./tool"
+
+import { ToolDefinition, ToolFailure, ToolOutput, type ToolCall } from "@neurocode-ai/llm"
+import { Effect, JsonSchema, Schema } from "effect"
+import type { AgentV2 } from "../agent"
+import type { SessionMessage } from "../session/message"
+import type { SessionSchema } from "../session/schema"
+
+export interface Context {
+  readonly sessionID: SessionSchema.ID
+  readonly agent: AgentV2.ID
+  readonly assistantMessageID: SessionMessage.ID
+  readonly toolCallID: string
+}
+
+export type SchemaType<A> = Schema.Codec<A, any, never, never>
+
+declare const TypeId: unique symbol
+
+export interface Definition<Input extends SchemaType<any>, Output extends SchemaType<any>> {
+  readonly [TypeId]: {
+    readonly _Input: Input
+    readonly _Output: Output
+  }
+}
+
+export type AnyTool = Definition<any, any>
+export const Failure = ToolFailure
+export type Failure = ToolFailure
+
+export class RegistrationError extends Schema.TaggedErrorClass<RegistrationError>()("Tool.RegistrationError", {
+  name: Schema.String,
+  message: Schema.String,
+}) {}
+
+export type Content =
+  | { readonly type: "text"; readonly text: string }
+  | { readonly type: "file"; readonly data: string; readonly mime: string; readonly name?: string }
+
+type Config<
+  Input extends SchemaType<any>,
+  Output extends SchemaType<any>,
+  Structured extends SchemaType<any> = Output,
+> = {
+  readonly description: string
+  readonly input: Input
+  readonly output: Output
+  readonly structured?: Structured
+  readonly toStructuredOutput?: (input: {
+    readonly input: Schema.Schema.Type<Input>
+    readonly output: Output["Encoded"]
+  }) => Schema.Schema.Type<Structured>
+  readonly execute: (
+    input: Schema.Schema.Type<Input>,
+    context: Context,
+  ) => Effect.Effect<Schema.Schema.Type<Output>, ToolFailure>
+  readonly toModelOutput?: (input: {
+    readonly input: Schema.Schema.Type<Input>
+    readonly output: Output["Encoded"]
+  }) => ReadonlyArray<Content>
+}
+
+type Runtime = {
+  readonly permission?: string
+  readonly definition: (name: string) => ToolDefinition
+  readonly settle: (call: ToolCall, context: Context) => Effect.Effect<ToolOutput, ToolFailure>
+}
+
+const runtimes = new WeakMap<AnyTool, Runtime>()
+
+export function make<
+  Input extends SchemaType<any>,
+  Output extends SchemaType<any>,
+  Structured extends SchemaType<any> = Output,
+>(config: Config<Input, Output, Structured>): Definition<Input, Structured> {
+  const tool = Object.freeze({}) as Definition<Input, Structured>
+  const definitions = new Map<string, ToolDefinition>()
+  runtimes.set(tool, {
+    definition: (name) => {
+      const cached = definitions.get(name)
+      if (cached) return cached
+      const definition = new ToolDefinition({
+        name,
+        description: config.description,
+        inputSchema: toJsonSchema(config.input),
+        outputSchema: toJsonSchema(config.structured ?? config.output),
+      })
+      definitions.set(name, definition)
+      return definition
+    },
+    settle: (call, context) =>
+      Schema.decodeUnknownEffect(config.input)(call.input).pipe(
+        Effect.mapError((error) => new ToolFailure({ message: `Invalid tool input: ${error.message}` })),
+        Effect.flatMap((input) =>
+          config.execute(input, context).pipe(
+            Effect.flatMap((output) =>
+              Schema.encodeEffect(config.output)(output).pipe(
+                Effect.flatMap((output) => {
+                  if (!config.structured || !config.toStructuredOutput)
+                    return Effect.succeed({ output, structured: output })
+                  return Schema.encodeEffect(config.structured)(config.toStructuredOutput({ input, output })).pipe(
+                    Effect.map((structured) => ({ output, structured })),
+                  )
+                }),
+                Effect.mapError(
+                  (error) =>
+                    new ToolFailure({
+                      message: `Tool returned an invalid value for its output schema: ${error.message}`,
+                    }),
+                ),
+              ),
+            ),
+            Effect.map(({ output, structured }) => ({
+              structured,
+              content:
+                config.toModelOutput?.({ input, output }).map((part) =>
+                  part.type === "text"
+                    ? { type: "text" as const, text: part.text }
+                    : {
+                        type: "file" as const,
+                        uri: `data:${part.mime};base64,${part.data}`,
+                        mime: part.mime,
+                        name: part.name,
+                      },
+                ) ?? (typeof output === "string" ? [{ type: "text" as const, text: output }] : []),
+            })),
+          ),
+        ),
+      ),
+  })
+  return tool
+}
+
+export const validateName = (name: string) =>
+  /^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(name)
+    ? Effect.void
+    : Effect.fail(new RegistrationError({ name, message: `Invalid tool name: ${name}` }))
+
+export const withPermission = <Input extends SchemaType<any>, Output extends SchemaType<any>>(
+  tool: Definition<Input, Output>,
+  permission: string,
+) => {
+  const decorated = Object.freeze({}) as Definition<Input, Output>
+  runtimes.set(decorated, { ...runtimeOf(tool), permission })
+  return decorated
+}
+
+export const permission = (tool: AnyTool, name: string) => runtimeOf(tool).permission ?? name
+export const definition = (name: string, tool: AnyTool) => runtimeOf(tool).definition(name)
+export const settle = (tool: AnyTool, call: ToolCall, context: Context) => runtimeOf(tool).settle(call, context)
+
+function runtimeOf(tool: AnyTool) {
+  const runtime = runtimes.get(tool)
+  if (!runtime) throw new TypeError("Invalid Core Tool value")
+  return runtime
+}
+
+function toJsonSchema(schema: Schema.Top): JsonSchema.JsonSchema {
+  const document = Schema.toJsonSchemaDocument(schema)
+  if (Object.keys(document.definitions).length === 0) return document.schema
+  return { ...document.schema, $defs: document.definitions }
+}

package/src/tool/tools.ts

@@ -0,0 +1,13 @@
+export * as Tools from "./tools"
+
+import { Context, Effect, Scope } from "effect"
+import { Tool } from "./tool"
+
+export interface Interface {
+  readonly register: (
+    tools: Readonly<Record<string, Tool.AnyTool>>,
+  ) => Effect.Effect<void, Tool.RegistrationError, Scope.Scope>
+}
+
+/** Narrow registration-only Location capability. */
+export class Service extends Context.Service<Service, Interface>()("@neurocode/v2/Tools") {}

package/src/tool/webfetch.ts

@@ -0,0 +1,218 @@
+export * as WebFetchTool from "./webfetch"
+
+import { ToolFailure } from "@neurocode-ai/llm"
+import { Duration, Effect, Layer, Schema } from "effect"
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
+import { Parser } from "htmlparser2"
+import TurndownService from "turndown"
+import { makeLocationNode } from "../effect/app-node"
+import { LayerNodePlatform } from "../effect/app-node-platform"
+import { PermissionV2 } from "../permission"
+import { collectBoundedResponseBody } from "./http-body"
+import { ToolRegistry } from "./registry"
+import { Tool } from "./tool"
+import { Tools } from "./tools"
+
+export const name = "webfetch"
+export const MAX_RESPONSE_BYTES = 5 * 1024 * 1024
+export const DEFAULT_TIMEOUT_SECONDS = 30
+export const MAX_TIMEOUT_SECONDS = 120
+
+export const description = `Fetch content from an HTTP or HTTPS URL and return it as text, markdown, or HTML. Markdown is the default.
+
+Use a more targeted tool when one is available. This tool is read-only. Large text results may be replaced with a preview while the complete output is retained in managed storage.`
+
+const Timeout = Schema.Number.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(MAX_TIMEOUT_SECONDS))
+
+export const Input = Schema.Struct({
+  url: Schema.String.annotate({ description: "The HTTP or HTTPS URL to fetch content from" }),
+  format: Schema.Literals(["text", "markdown", "html"])
+    .annotate({ description: "The format to return the content in. Defaults to markdown." })
+    .pipe(Schema.withDecodingDefault(Effect.succeed("markdown" as const))),
+  timeout: Timeout.pipe(Schema.optional).annotate({
+    description: `Optional timeout in seconds (maximum: ${MAX_TIMEOUT_SECONDS})`,
+  }),
+})
+
+const Output = Schema.Struct({
+  url: Schema.String,
+  contentType: Schema.String,
+  format: Input.fields.format,
+  output: Schema.String,
+})
+
+type Format = (typeof Input.Type)["format"]
+
+const acceptHeader = (format: Format) => {
+  switch (format) {
+    case "markdown":
+      return "text/markdown;q=1.0, text/x-markdown;q=0.9, text/plain;q=0.8, text/html;q=0.7, */*;q=0.1"
+    case "text":
+      return "text/plain;q=1.0, text/markdown;q=0.9, text/html;q=0.8, */*;q=0.1"
+    case "html":
+      return "text/html;q=1.0, application/xhtml+xml;q=0.9, text/plain;q=0.8, text/markdown;q=0.7, */*;q=0.1"
+  }
+  return "*/*"
+}
+
+const headers = (format: Format, userAgent: string) => ({
+  "User-Agent": userAgent,
+  Accept: acceptHeader(format),
+  "Accept-Language": "en-US,en;q=0.9",
+})
+
+const browserUserAgent =
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"
+
+const isCloudflareChallenge = (error: unknown) => {
+  if (!error || typeof error !== "object" || !("reason" in error)) return false
+  const reason = error.reason
+  if (
+    !reason ||
+    typeof reason !== "object" ||
+    !("_tag" in reason) ||
+    reason._tag !== "StatusCodeError" ||
+    !("response" in reason)
+  )
+    return false
+  const response = reason.response as HttpClientResponse.HttpClientResponse
+  return response.status === 403 && response.headers["cf-mitigated"] === "challenge"
+}
+
+const request = (url: string, format: Format, userAgent = browserUserAgent) =>
+  HttpClientRequest.get(url).pipe(HttpClientRequest.setHeaders(headers(format, userAgent)))
+
+const assertHttpUrl = (url: URL) => {
+  if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("URL must use http:// or https://")
+}
+
+const execute = (http: HttpClient.HttpClient, url: string, format: Format, userAgent = browserUserAgent) =>
+  http.execute(request(url, format, userAgent)).pipe(Effect.flatMap(HttpClientResponse.filterStatusOk))
+
+const collectBody = (response: HttpClientResponse.HttpClientResponse) =>
+  collectBoundedResponseBody(
+    response,
+    MAX_RESPONSE_BYTES,
+    () => new Error(`Response too large (exceeds ${MAX_RESPONSE_BYTES} byte limit)`),
+  )
+
+const mimeFrom = (contentType: string) => contentType.split(";", 1)[0]?.trim().toLowerCase() ?? ""
+const isImageAttachment = (mime: string) =>
+  mime.startsWith("image/") && mime !== "image/svg+xml" && mime !== "image/vnd.fastbidsheet"
+const isTextualMime = (mime: string) =>
+  !mime ||
+  mime.startsWith("text/") ||
+  mime === "application/json" ||
+  mime.endsWith("+json") ||
+  mime === "application/xml" ||
+  mime.endsWith("+xml") ||
+  mime === "application/javascript" ||
+  mime === "application/x-javascript"
+const convert = (content: string, contentType: string, format: Format) => {
+  if (!contentType.includes("text/html")) return content
+  if (format === "markdown") return convertHTMLToMarkdown(content)
+  if (format === "text") return extractTextFromHTML(content)
+  return content
+}
+
+const layer = Layer.effectDiscard(
+  Effect.gen(function* () {
+    const tools = yield* Tools.Service
+    const http = yield* HttpClient.HttpClient
+    const permission = yield* PermissionV2.Service
+
+    yield* tools
+      .register({
+        [name]: Tool.make({
+          description,
+          input: Input,
+          output: Output,
+          toModelOutput: ({ output }) => [{ type: "text", text: output.output }],
+          execute: (input, context) =>
+            Effect.gen(function* () {
+              yield* Effect.try({
+                try: () => assertHttpUrl(new URL(input.url)),
+                catch: (error) => error,
+              })
+
+              yield* permission.assert({
+                action: name,
+                resources: [input.url],
+                save: ["*"],
+                metadata: input,
+                sessionID: context.sessionID,
+                agent: context.agent,
+                source: { type: "tool", messageID: context.assistantMessageID, callID: context.toolCallID },
+              })
+
+              const { body, contentType } = yield* Effect.gen(function* () {
+                const response = yield* execute(http, input.url, input.format).pipe(
+                  Effect.catchIf(isCloudflareChallenge, () => execute(http, input.url, input.format, "neurocode")),
+                )
+                const contentType = response.headers["content-type"] || ""
+                const mime = mimeFrom(contentType)
+                if (isImageAttachment(mime))
+                  return yield* Effect.fail(new Error(`Unsupported fetched image content type: ${mime}`))
+                if (!isTextualMime(mime))
+                  return yield* Effect.fail(new Error(`Unsupported fetched file content type: ${mime}`))
+                return { body: yield* collectBody(response), contentType }
+              }).pipe(
+                Effect.timeoutOrElse({
+                  duration: Duration.seconds(input.timeout ?? DEFAULT_TIMEOUT_SECONDS),
+                  orElse: () => Effect.fail(new Error("Request timed out")),
+                }),
+              )
+              const content = new TextDecoder().decode(body)
+              const output = yield* Effect.try({
+                try: () => convert(content, contentType, input.format),
+                catch: (error) => error,
+              })
+              return {
+                url: input.url,
+                contentType,
+                format: input.format,
+                output,
+              }
+            }).pipe(Effect.mapError(() => new ToolFailure({ message: `Unable to fetch ${input.url}` }))),
+        }),
+      })
+      .pipe(Effect.orDie)
+  }),
+)
+
+export const node = makeLocationNode({
+  name: "tool/webfetch",
+  layer,
+  deps: [ToolRegistry.node, PermissionV2.node, LayerNodePlatform.httpClient],
+})
+
+export function extractTextFromHTML(html: string) {
+  let text = ""
+  let skipDepth = 0
+  const parser = new Parser({
+    onopentag(name) {
+      if (skipDepth > 0 || ["script", "style", "noscript", "iframe", "object", "embed"].includes(name)) skipDepth++
+    },
+    ontext(input) {
+      if (skipDepth === 0) text += input
+    },
+    onclosetag() {
+      if (skipDepth > 0) skipDepth--
+    },
+  })
+  parser.write(html)
+  parser.end()
+  return text.trim()
+}
+
+export function convertHTMLToMarkdown(html: string) {
+  const turndown = new TurndownService({
+    headingStyle: "atx",
+    hr: "---",
+    bulletListMarker: "-",
+    codeBlockStyle: "fenced",
+    emDelimiter: "*",
+  })
+  turndown.remove(["script", "style", "meta", "link"])
+  return turndown.turndown(html)
+}