@yolk-sdk/agent 0.0.1-canary.0

package/src/tools/registry.ts

@@ -0,0 +1,228 @@
+import { Array as Arr, Effect, Layer, Option } from 'effect'
+import * as Schema from 'effect/Schema'
+import { ToolError, ToolExecutor } from '@yolk-sdk/agent/loop'
+import { ToolDef, type ToolApprovalPolicy, type ToolCall, type ToolResult } from '@yolk-sdk/agent/protocol'
+
+export const ToolAccess = Schema.Literals(['read', 'write', 'destructive'])
+export type ToolAccess = typeof ToolAccess.Type
+
+export class ToolRegistryError extends Schema.TaggedErrorClass<ToolRegistryError>()(
+  'ToolRegistryError',
+  {
+    message: Schema.String,
+    cause: Schema.Literals(['duplicate_tool'])
+  }
+) {}
+
+export type ToolExecutionInput<Context> = {
+  readonly call: ToolCall
+  readonly context: Context
+}
+
+export type SchemaToolExecutionInput<Context, Params> = ToolExecutionInput<Context> & {
+  readonly params: Params
+}
+
+export type ToolRegistration<Context> = {
+  readonly def: ToolDef
+  readonly access: ToolAccess
+  readonly approval?: ToolApprovalPolicy
+  readonly isEnabled?: (context: Context) => Effect.Effect<boolean, ToolRegistryError>
+  readonly execute: (input: ToolExecutionInput<Context>) => Effect.Effect<ToolResult, ToolError>
+}
+
+type ToolParamsSchema = Schema.Schema<unknown> & { readonly DecodingServices: never }
+
+export const EmptyToolParams = Schema.Record(Schema.String, Schema.Never)
+
+export type MakeToolOptions<Context, ParamsSchema extends ToolParamsSchema> = {
+  readonly name: string
+  readonly description: string
+  readonly parameters: ParamsSchema
+  readonly access: ToolAccess
+  readonly approval?: ToolApprovalPolicy
+  readonly isEnabled?: (context: Context) => Effect.Effect<boolean, ToolRegistryError>
+  readonly invalidParamsMessage?: (error: unknown) => string
+  readonly execute: (
+    input: SchemaToolExecutionInput<Context, ParamsSchema['Type']>
+  ) => Effect.Effect<ToolResult, ToolError>
+}
+
+export type ToolModule<Context> = {
+  readonly id: string
+  readonly tools: ReadonlyArray<ToolRegistration<Context>>
+}
+
+export type ToolMetadata = {
+  readonly moduleId: string
+  readonly name: string
+  readonly access: ToolAccess
+}
+
+type ResolvedRegistration<Context> = {
+  readonly moduleId: string
+  readonly tool: ToolRegistration<Context>
+}
+
+export type ResolvedToolSet = {
+  readonly tools: ReadonlyArray<ToolDef>
+  readonly metadata: ReadonlyArray<ToolMetadata>
+  readonly execute: (call: ToolCall) => Effect.Effect<ToolResult, ToolError>
+}
+
+const enabled = <Context>(tool: ToolRegistration<Context>, context: Context) =>
+  tool.isEnabled === undefined ? Effect.succeed(true) : tool.isEnabled(context)
+
+const resolveModuleTools = <Context>(toolModule: ToolModule<Context>, context: Context) =>
+  Effect.forEach(toolModule.tools, tool =>
+    enabled(tool, context).pipe(
+      Effect.map(isToolEnabled =>
+        isToolEnabled ? Option.some({ moduleId: toolModule.id, tool }) : Option.none()
+      )
+    )
+  ).pipe(Effect.map(Arr.getSomes))
+
+const duplicateToolError = (name: string) =>
+  new ToolRegistryError({
+    cause: 'duplicate_tool',
+    message: `Duplicate tool registered: ${name}`
+  })
+
+const missingToolError = (name: string) =>
+  new ToolError({
+    tool: name,
+    message: `Tool is not configured: ${name}`,
+    cause: 'not_found'
+  })
+
+const unknownToMessage = (error: unknown) =>
+  error instanceof Error ? error.message : String(error)
+
+const objectField = (input: unknown, key: string) =>
+  input !== null && typeof input === 'object' ? Object.getOwnPropertyDescriptor(input, key)?.value : undefined
+
+const isObjectRecord = (input: unknown): input is Readonly<Record<string, unknown>> =>
+  input !== null && typeof input === 'object' && !Array.isArray(input)
+
+const localDefinitionName = (ref: unknown) => {
+  if (typeof ref !== 'string') {
+    return undefined
+  }
+
+  const prefix = '#/$defs/'
+
+  return ref.startsWith(prefix) ? ref.slice(prefix.length) : undefined
+}
+
+const hasJsonSchemaType = (input: unknown, type: string) => objectField(input, 'type') === type
+
+const isEmptyStructJsonSchema = (schema: unknown) => {
+  const anyOf = objectField(schema, 'anyOf')
+
+  return Array.isArray(anyOf) &&
+    anyOf.length === 2 &&
+    anyOf.some(item => hasJsonSchemaType(item, 'object')) &&
+    anyOf.some(item => hasJsonSchemaType(item, 'array'))
+}
+
+const isEmptyRecordJsonSchema = (schema: unknown) =>
+  hasJsonSchemaType(schema, 'object') &&
+  objectField(schema, 'additionalProperties') === false &&
+  objectField(schema, 'properties') === undefined &&
+  objectField(schema, 'required') === undefined
+
+const emptyObjectJsonSchema = {
+  type: 'object',
+  properties: {},
+  required: [],
+  additionalProperties: false
+}
+
+const jsonSchemaFromSchema = (schema: Schema.Top) => {
+  const document = Schema.toJsonSchemaDocument(schema)
+  const definitionName = localDefinitionName(objectField(document.schema, '$ref'))
+  const localDefinition = definitionName === undefined
+    ? undefined
+    : Object.getOwnPropertyDescriptor(document.definitions, definitionName)?.value
+  const rootSchema = isObjectRecord(localDefinition) ? localDefinition : document.schema
+  const remainingDefinitions = definitionName === undefined
+    ? document.definitions
+    : Object.fromEntries(
+        Object.entries(document.definitions).filter(([name]) => name !== definitionName)
+      )
+  const jsonSchema = isEmptyStructJsonSchema(rootSchema) || isEmptyRecordJsonSchema(rootSchema)
+    ? emptyObjectJsonSchema
+    : rootSchema
+
+  return Object.keys(remainingDefinitions).length > 0
+    ? { ...jsonSchema, $defs: remainingDefinitions }
+    : jsonSchema
+}
+
+export const makeTool = <Context, ParamsSchema extends ToolParamsSchema>(
+  options: MakeToolOptions<Context, ParamsSchema>
+): ToolRegistration<Context> => ({
+  def: ToolDef.make({
+    name: options.name,
+    description: options.description,
+    parameters: jsonSchemaFromSchema(options.parameters),
+    approval: options.approval
+  }),
+  access: options.access,
+  approval: options.approval,
+  isEnabled: options.isEnabled,
+  execute: ({ call, context }) =>
+    Schema.decodeUnknownEffect(options.parameters)(call.params).pipe(
+      Effect.mapError(error =>
+        new ToolError({
+          tool: options.name,
+          message: options.invalidParamsMessage?.(error) ?? `Invalid ${options.name} arguments: ${unknownToMessage(error)}`,
+          cause: 'validation'
+        })
+      ),
+      Effect.flatMap(params => options.execute({ call, context, params }))
+    )
+})
+
+const findDuplicateToolName = <Context>(resolved: ReadonlyArray<ResolvedRegistration<Context>>) => {
+  const names = Arr.map(resolved, item => item.tool.def.name)
+
+  return Arr.findFirst(names, (name, index) => names.indexOf(name) !== index)
+}
+
+export const resolveTools = <Context>(
+  modules: ReadonlyArray<ToolModule<Context>>,
+  context: Context
+): Effect.Effect<ResolvedToolSet, ToolRegistryError> =>
+  Effect.gen(function* () {
+    const resolvedByModule = yield* Effect.forEach(modules, toolModule =>
+      resolveModuleTools(toolModule, context)
+    )
+    const resolved = Arr.flatten(resolvedByModule)
+    const duplicateName = findDuplicateToolName(resolved)
+
+    if (Option.isSome(duplicateName)) {
+      return yield* Effect.fail(duplicateToolError(duplicateName.value))
+    }
+
+    const tools = Arr.map(resolved, item => item.tool.def)
+    const metadata = Arr.map(resolved, item => ({
+      moduleId: item.moduleId,
+      name: item.tool.def.name,
+      access: item.tool.access
+    }))
+
+    const execute = (call: ToolCall) =>
+      Option.match(
+        Arr.findFirst(resolved, item => item.tool.def.name === call.name),
+        {
+          onNone: () => Effect.fail(missingToolError(call.name)),
+          onSome: match => match.tool.execute({ call, context })
+        }
+      )
+
+    return { tools, metadata, execute }
+  })
+
+export const makeToolExecutorLayer = (toolSet: ResolvedToolSet) =>
+  Layer.succeed(ToolExecutor, ToolExecutor.of({ execute: toolSet.execute }))

package/src/tools/task.ts

@@ -0,0 +1,132 @@
+import { Effect } from 'effect'
+import * as Schema from 'effect/Schema'
+import { ToolError } from '@yolk-sdk/agent/loop'
+import { ToolResult, type ToolCall } from '@yolk-sdk/agent/protocol'
+import { makeTool, type ToolModule, type ToolRegistration } from './registry.ts'
+
+export const taskToolName = 'task'
+
+const TaskToolParams = Schema.Struct({
+  description: Schema.String.pipe(Schema.annotate({ description: 'A short 3-5 word description of the task.' })),
+  prompt: Schema.String.pipe(
+    Schema.annotate({
+      description: 'The complete task instructions for the subagent, including all context it needs.'
+    })
+  ),
+  subagent_type: Schema.String.pipe(
+    Schema.annotate({ description: 'The specialized subagent type to use for this task.' })
+  )
+})
+
+export type TaskToolParams = typeof TaskToolParams.Type
+
+export type TaskSubagentDefinition = {
+  readonly name: string
+  readonly description: string
+}
+
+export type TaskExecutionInput<Context> = {
+  readonly call: ToolCall
+  readonly context: Context
+  readonly params: TaskToolParams
+}
+
+export type TaskToolOptions<Context> = {
+  readonly subagents: ReadonlyArray<TaskSubagentDefinition>
+  readonly execute: (input: TaskExecutionInput<Context>) => Effect.Effect<ToolResult, ToolError>
+}
+
+const taskToolError = (message: string, cause: ToolError['cause']) =>
+  new ToolError({
+    tool: taskToolName,
+    message,
+    cause
+  })
+
+const trimmedTaskParams = (params: TaskToolParams) => ({
+  description: params.description.trim(),
+  prompt: params.prompt.trim(),
+  subagent_type: params.subagent_type.trim()
+})
+
+const validateTaskParams = (params: TaskToolParams) => {
+  const trimmed = trimmedTaskParams(params)
+
+  if (trimmed.description.length === 0) {
+    return Effect.fail(taskToolError('description must not be empty', 'validation'))
+  }
+
+  if (trimmed.prompt.length === 0) {
+    return Effect.fail(taskToolError('prompt must not be empty', 'validation'))
+  }
+
+  if (trimmed.subagent_type.length === 0) {
+    return Effect.fail(taskToolError('subagent_type must not be empty', 'validation'))
+  }
+
+  return Effect.succeed(trimmed)
+}
+
+const findSubagent = (subagents: ReadonlyArray<TaskSubagentDefinition>, name: string) =>
+  subagents.find(subagent => subagent.name === name)
+
+const requireKnownSubagent = (
+  subagents: ReadonlyArray<TaskSubagentDefinition>,
+  name: string
+) => {
+  const subagent = findSubagent(subagents, name)
+
+  return subagent === undefined
+    ? Effect.fail(taskToolError(`Unknown subagent type: ${name}`, 'validation'))
+    : Effect.succeed(subagent)
+}
+
+const subagentDescription = (subagent: TaskSubagentDefinition) =>
+  `- ${subagent.name}: ${subagent.description}`
+
+const taskToolDescription = (subagents: ReadonlyArray<TaskSubagentDefinition>) =>
+  [
+    'Launch a new agent to handle complex, multistep tasks autonomously.',
+    'Use this when delegating focused work to a specialized subagent would save context or allow parallel exploration.',
+    'To run subagents in parallel, call this task tool multiple times in the same assistant response.',
+    'Yolk runs same-turn task calls concurrently automatically.',
+    'A fresh subagent only sees the prompt you provide, so include all required context.',
+    'Subagents can use their normal tools but cannot launch further task subagents in v1.',
+    subagents.length === 0
+      ? 'No subagent types are currently available.'
+      : `Available subagent types:\n${subagents.map(subagentDescription).join('\n')}`
+  ].join('\n\n')
+
+export const makeTaskToolRegistration = <Context>(
+  options: TaskToolOptions<Context>
+): ToolRegistration<Context> => makeTool({
+  name: taskToolName,
+  description: taskToolDescription(options.subagents),
+  parameters: TaskToolParams,
+  access: 'read',
+  invalidParamsMessage: error => `Invalid task arguments: ${error instanceof Error ? error.message : String(error)}`,
+  execute: ({ call, context, params }) =>
+    Effect.gen(function* () {
+      if (call.name !== taskToolName) {
+        return yield* Effect.fail(taskToolError(`Tool is not configured: ${call.name}`, 'not_found'))
+      }
+
+      const normalizedParams = yield* validateTaskParams(params)
+      yield* requireKnownSubagent(options.subagents, normalizedParams.subagent_type)
+
+      return yield* options.execute({ call, context, params: normalizedParams })
+    })
+})
+
+export const makeTaskToolDef = (subagents: ReadonlyArray<TaskSubagentDefinition>) =>
+  makeTaskToolRegistration({
+    subagents,
+    execute: ({ call }) => Effect.succeed(ToolResult.make({ toolCallId: call.id, content: '' }))
+  }).def
+
+export const makeTaskToolModule = <Context>(options: TaskToolOptions<Context>): ToolModule<Context> => ({
+  id: 'task',
+  tools: [makeTaskToolRegistration(options)]
+})
+
+export const formatTaskResult = (output: string) => ['<task_result>', output, '</task_result>'].join('\n')