artificial-code 1.17.13

package/src/tool/skill.txt

@@ -0,0 +1,5 @@
+Load a specialized skill when the task at hand matches one of the skills listed in the system prompt.
+
+Use this tool to inject the skill's instructions and resources into 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 skills listed in your system prompt.

package/src/tool/task.ts

@@ -0,0 +1,346 @@
+import * as Tool from "./tool"
+import DESCRIPTION from "./task.txt"
+import { ToolJsonSchema } from "./json-schema"
+import { SessionV1 } from "@ac/core/v1/session"
+import { BackgroundJob } from "@/background/job"
+import { Session } from "@/session/session"
+import { SessionID, MessageID } from "../session/schema"
+import { MessageV2 } from "../session/message-v2"
+import { Agent } from "../agent/agent"
+import { deriveSubagentSessionPermission } from "../agent/subagent-permissions"
+import type { SessionPrompt } from "../session/prompt"
+import { Config } from "@/config/config"
+import { Effect, Exit, Schema, Scope } from "effect"
+import { EffectBridge } from "@/effect/bridge"
+import { RuntimeFlags } from "@/effect/runtime-flags"
+import { Database } from "@ac/core/database/database"
+
+export interface TaskPromptOps {
+  cancel(sessionID: SessionID): Effect.Effect<void>
+  resolvePromptParts(template: string): Effect.Effect<SessionPrompt.PromptInput["parts"]>
+  prompt(input: SessionPrompt.PromptInput): Effect.Effect<SessionV1.WithParts>
+}
+
+const id = "task"
+const BACKGROUND_DESCRIPTION = [
+  "Background mode: background=true launches the subagent asynchronously and returns immediately.",
+  "Foreground is the default; use it when you need the result before continuing.",
+  "Use background only for independent work that can run while you continue elsewhere.",
+  "You will be notified automatically when it finishes.",
+].join(" ")
+const BACKGROUND_STARTED = [
+  "The task is working in the background. You will be notified automatically when it finishes.",
+  "DO NOT sleep, poll for progress, ask the task for status, or duplicate this task's work — avoid working with the same files or topics it is using.",
+  "Work on non-overlapping tasks, or briefly tell the user what you launched and end your response.",
+].join("\n")
+const BACKGROUND_UPDATED = [
+  "Additional context sent to the running background task.",
+  "The task is still working in the background. You will be notified automatically when it finishes.",
+  "DO NOT sleep, poll for progress, ask the task for status, or duplicate this task's work — avoid working with the same files or topics it is using.",
+  "Work on non-overlapping tasks, or briefly tell the user what you sent and end your response.",
+].join("\n")
+
+const BaseParameterFields = {
+  description: Schema.String.annotate({ description: "A short (3-5 words) description of the task" }),
+  prompt: Schema.String.annotate({ description: "The task for the agent to perform" }),
+  subagent_type: Schema.String.annotate({ description: "The type of specialized agent to use for this task" }),
+  task_id: Schema.optional(Schema.String).annotate({
+    description:
+      "This should only be set if you mean to resume a previous task (you can pass a prior task_id and the task will continue the same subagent session as before instead of creating a fresh one)",
+  }),
+  command: Schema.optional(Schema.String).annotate({ description: "The command that triggered this task" }),
+}
+
+const BaseParameters = Schema.Struct(BaseParameterFields)
+
+export const Parameters = Schema.Struct({
+  ...BaseParameterFields,
+  background: Schema.optional(Schema.Boolean).annotate({
+    description:
+      "Run the agent in the background. You will be notified when it completes. DO NOT sleep, poll, or proactively check on its progress",
+  }),
+})
+
+function renderOutput(input: {
+  sessionID: SessionID
+  state: "running" | "completed" | "error"
+  summary?: string
+  text: string
+}) {
+  const tag = input.state === "error" ? "task_error" : "task_result"
+  return [
+    `<task id="${input.sessionID}" state="${input.state}">`,
+    ...(input.summary ? [`<summary>${input.summary}</summary>`] : []),
+    `<${tag}>`,
+    input.text,
+    `</${tag}>`,
+    "</task>",
+  ].join("\n")
+}
+
+export const TaskTool = Tool.define(
+  id,
+  Effect.gen(function* () {
+    const agent = yield* Agent.Service
+    const background = yield* BackgroundJob.Service
+    const config = yield* Config.Service
+    const sessions = yield* Session.Service
+    const scope = yield* Scope.Scope
+    const flags = yield* RuntimeFlags.Service
+    const database = yield* Database.Service
+
+    const run = Effect.fn("TaskTool.execute")(function* (
+      params: Schema.Schema.Type<typeof Parameters>,
+      ctx: Tool.Context,
+    ) {
+      const cfg = yield* config.get()
+      const runInBackground = params.background === true
+      if (runInBackground && !flags.experimentalBackgroundSubagents) {
+        return yield* Effect.fail(
+          new Error("Background subagents require AC_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true"),
+        )
+      }
+
+      if (!ctx.extra?.bypassAgentCheck) {
+        yield* ctx.ask({
+          permission: id,
+          patterns: [params.subagent_type],
+          always: ["*"],
+          metadata: {
+            description: params.description,
+            subagent_type: params.subagent_type,
+          },
+        })
+      }
+
+      const next = yield* agent.get(params.subagent_type)
+      if (!next) {
+        return yield* Effect.fail(new Error(`Unknown agent type: ${params.subagent_type} is not a valid agent type`))
+      }
+
+      const session = params.task_id
+        ? yield* sessions.get(SessionID.make(params.task_id)).pipe(Effect.catchCause(() => Effect.succeed(undefined)))
+        : undefined
+      const parent = yield* sessions.get(ctx.sessionID)
+      const childPermission = deriveSubagentSessionPermission({
+        parentSessionPermission: parent.permission ?? [],
+        subagent: next,
+      })
+      const childToolDenies = [
+        ...(next.permission.some((rule) => rule.permission === "todowrite")
+          ? []
+          : [{ permission: "todowrite" as const, pattern: "*" as const, action: "deny" as const }]),
+        ...(next.permission.some((rule) => rule.permission === id)
+          ? []
+          : [{ permission: id, pattern: "*" as const, action: "deny" as const }]),
+        ...(cfg.experimental?.primary_tools?.map((permission) => ({
+          permission,
+          pattern: "*" as const,
+          action: "deny" as const,
+        })) ?? []),
+      ]
+      const nextSession =
+        session ??
+        (yield* sessions.create({
+          parentID: ctx.sessionID,
+          title: params.description + ` (@${next.name} subagent)`,
+          agent: next.name,
+          permission: [
+            ...childPermission,
+            ...childToolDenies.filter(
+              (deny) =>
+                !childPermission.some(
+                  (rule) =>
+                    rule.permission === deny.permission && rule.pattern === deny.pattern && rule.action === deny.action,
+                ),
+            ),
+          ],
+        }))
+
+      const msg = yield* MessageV2.get({ sessionID: ctx.sessionID, messageID: ctx.messageID }).pipe(
+        Effect.provideService(Database.Service, database),
+        Effect.orDie,
+      )
+      if (msg.info.role !== "assistant") return yield* Effect.fail(new Error("Not an assistant message"))
+      const variant = msg.info.variant
+
+      const model = next.model ?? {
+        modelID: msg.info.modelID,
+        providerID: msg.info.providerID,
+      }
+      const metadata = {
+        parentSessionId: ctx.sessionID,
+        sessionId: nextSession.id,
+        model,
+        ...(runInBackground ? { background: true } : {}),
+      }
+
+      yield* ctx.metadata({
+        title: params.description,
+        metadata,
+      })
+
+      const ops = ctx.extra?.promptOps as TaskPromptOps
+      if (!ops) return yield* Effect.fail(new Error("TaskTool requires promptOps in ctx.extra"))
+
+      const runTask = Effect.fn("TaskTool.runTask")(function* () {
+        const parts = yield* ops.resolvePromptParts(params.prompt)
+        const result = yield* ops.prompt({
+          messageID: MessageID.ascending(),
+          sessionID: nextSession.id,
+          model: {
+            modelID: model.modelID,
+            providerID: model.providerID,
+          },
+          variant: next.model ? undefined : variant,
+          agent: next.name,
+          parts,
+        })
+        return result.parts.findLast((item) => item.type === "text")?.text ?? ""
+      })
+
+      const inject = Effect.fn("TaskTool.injectBackgroundResult")(function* (
+        state: "completed" | "error",
+        text: string,
+      ) {
+        const currentParent = yield* sessions.get(ctx.sessionID)
+        yield* ops
+          .prompt({
+            sessionID: ctx.sessionID,
+            agent: currentParent.agent ?? ctx.agent,
+            variant,
+            parts: [
+              {
+                type: "text",
+                synthetic: true,
+                text: renderOutput({
+                  sessionID: nextSession.id,
+                  state,
+                  summary:
+                    state === "completed"
+                      ? `Background task completed: ${params.description}`
+                      : `Background task failed: ${params.description}`,
+                  text,
+                }),
+              },
+            ],
+          })
+          .pipe(Effect.ignore, Effect.forkIn(scope, { startImmediately: true }))
+      })
+
+      const notify = Effect.fn("TaskTool.notifyBackgroundResult")(function* (jobID: string) {
+        yield* background.wait({ id: jobID }).pipe(
+          Effect.flatMap((result) => {
+            if (result.info?.status === "completed") return inject("completed", result.info.output ?? "")
+            if (result.info?.status === "error") return inject("error", result.info.error ?? "")
+            return Effect.void
+          }),
+          Effect.forkIn(scope, { startImmediately: true }),
+        )
+      })
+
+      if (yield* background.extend({ id: nextSession.id, run: runTask() })) {
+        return {
+          title: params.description,
+          metadata: {
+            ...metadata,
+            background: true,
+            jobId: nextSession.id,
+          },
+          output: renderOutput({
+            sessionID: nextSession.id,
+            state: "running",
+            summary: "Background task updated",
+            text: BACKGROUND_UPDATED,
+          }),
+        }
+      }
+
+      const info = yield* background.start({
+        id: nextSession.id,
+        type: id,
+        title: params.description,
+        metadata,
+        onPromote: Effect.all([
+          ctx.metadata({
+            title: params.description,
+            metadata: { ...metadata, background: true, jobId: nextSession.id },
+          }),
+          notify(nextSession.id),
+        ]),
+        run: runTask().pipe(Effect.onInterrupt(() => ops.cancel(nextSession.id))),
+      })
+
+      function backgroundResult() {
+        return {
+          title: params.description,
+          metadata: {
+            ...metadata,
+            background: true,
+            jobId: info.id,
+          },
+          output: renderOutput({
+            sessionID: nextSession.id,
+            state: "running",
+            summary: "Background task started",
+            text: BACKGROUND_STARTED,
+          }),
+        }
+      }
+
+      if (runInBackground) {
+        yield* notify(info.id)
+        return backgroundResult()
+      }
+
+      const runCancel = yield* EffectBridge.make()
+      const cancel = ops.cancel(nextSession.id)
+
+      function onAbort() {
+        runCancel.fork(cancel)
+      }
+
+      return yield* Effect.acquireUseRelease(
+        Effect.sync(() => {
+          ctx.abort.addEventListener("abort", onAbort)
+        }),
+        () =>
+          Effect.gen(function* () {
+            const result = yield* Effect.raceFirst(
+              background.wait({ id: nextSession.id }).pipe(Effect.map((waited) => waited.info)),
+              background.waitForPromotion(nextSession.id),
+            )
+            if (result?.metadata?.background === true) return backgroundResult()
+            if (result?.status === "error") return yield* Effect.fail(new Error(result.error ?? "Task failed"))
+            if (result?.status === "cancelled") return yield* Effect.fail(new Error("Task cancelled"))
+            return {
+              title: params.description,
+              metadata,
+              output: renderOutput({ sessionID: nextSession.id, state: "completed", text: result?.output ?? "" }),
+            }
+          }),
+        (_, exit) =>
+          Effect.gen(function* () {
+            if (Exit.hasInterrupts(exit))
+              yield* Effect.all([cancel, background.cancel(nextSession.id)], { discard: true })
+          }).pipe(
+            Effect.ensuring(
+              Effect.sync(() => {
+                ctx.abort.removeEventListener("abort", onAbort)
+              }),
+            ),
+          ),
+      )
+    })
+
+    return {
+      description: flags.experimentalBackgroundSubagents
+        ? [DESCRIPTION, BACKGROUND_DESCRIPTION].join("\n\n")
+        : DESCRIPTION,
+      parameters: Parameters,
+      jsonSchema: flags.experimentalBackgroundSubagents ? undefined : ToolJsonSchema.fromSchema(BaseParameters),
+      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) =>
+        run(params, ctx).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/tool/task.txt

@@ -0,0 +1,19 @@
+Launch a new agent to handle complex, multistep tasks autonomously.
+
+When using the Task tool, you must specify a subagent_type parameter to select which agent type to use.
+
+When NOT to use the Task tool:
+- If you want to read a specific file path, use the Read or Glob tool instead of the Task tool, to find the match more quickly
+- If you are searching for a specific class definition like "class Foo", use the Grep tool instead, to find the match more quickly
+- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Task tool, to find the match more quickly
+- If no available agent is a good fit for the task, use other tools directly
+
+
+Usage notes:
+1. Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+2. Once you have delegated work to an agent, do not duplicate that work yourself. Continue with non-overlapping tasks, or wait for the result. For background tasks, you will be notified automatically when the result is ready.
+3. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result. The output includes a task_id you can reuse later to continue the same subagent session.
+4. Each agent invocation starts with a fresh context unless you provide task_id to resume the same subagent session (which continues with its previous messages and tool outputs). When starting fresh, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
+5. The agent's outputs should generally be trusted
+6. Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent. Tell it how to verify its work if possible (e.g., relevant test commands).
+7. If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.

package/src/tool/todo.ts

@@ -0,0 +1,46 @@
+import { Effect, Schema } from "effect"
+import * as Tool from "./tool"
+import DESCRIPTION_WRITE from "./todowrite.txt"
+import { Todo } from "../session/todo"
+
+export const Parameters = Schema.Struct({
+  todos: Schema.mutable(Schema.Array(Todo.Info)).annotate({ description: "The updated todo list" }),
+})
+
+type Metadata = {
+  todos: Todo.Info[]
+}
+
+export const TodoWriteTool = Tool.define<typeof Parameters, Metadata, Todo.Service>(
+  "todowrite",
+  Effect.gen(function* () {
+    const todo = yield* Todo.Service
+
+    return {
+      description: DESCRIPTION_WRITE,
+      parameters: Parameters,
+      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context<Metadata>) =>
+        Effect.gen(function* () {
+          yield* ctx.ask({
+            permission: "todowrite",
+            patterns: ["*"],
+            always: ["*"],
+            metadata: {},
+          })
+
+          yield* todo.update({
+            sessionID: ctx.sessionID,
+            todos: params.todos,
+          })
+
+          return {
+            title: `${params.todos.filter((x) => x.status !== "completed").length} todos`,
+            output: JSON.stringify(params.todos, null, 2),
+            metadata: {
+              todos: params.todos,
+            },
+          }
+        }),
+    } satisfies Tool.DefWithoutID<typeof Parameters, Metadata>
+  }),
+)

package/src/tool/todowrite.txt

@@ -0,0 +1,44 @@
+Create and maintain a structured task list for the current coding session. Tracks progress, organizes multi-step work, and surfaces status to the user.
+
+## When to use
+Use proactively when:
+- The task requires 3+ distinct steps or actions (not just 3 tool calls for a single conceptual step)
+- The work is non-trivial and benefits from planning
+- The user provides multiple tasks (numbered or comma-separated) or explicitly asks for a todo list
+- New instructions arrive - capture them as todos
+- You start a task - mark it `in_progress` (only one at a time) before working
+- You finish a task - mark it `completed` and add any follow-ups discovered during the work
+
+## When NOT to use
+Skip when:
+- The work is a single, straightforward task (or <3 trivial steps)
+- The request is purely informational or conversational
+- Tracking adds no organizational value
+
+## States
+- `pending` - not started
+- `in_progress` - actively working (exactly ONE at a time)
+- `completed` - finished successfully
+- `cancelled` - no longer needed
+
+## Rules
+- Update status in real time; don't batch completions
+- Mark `completed` only after the required work is actually done, including any required verification. Never based on intent.
+- Keep exactly one `in_progress` while work remains
+- If blocked or partial, keep it `in_progress` and add a follow-up todo describing the blocker
+- Preserve user-provided commands verbatim (flags, args, order)
+- Items should be specific and actionable; break large work into smaller steps
+
+## Examples
+
+Use it:
+- "Add a dark mode toggle and run the tests" -> multi-step feature + explicit verification
+- "Rename getCwd -> getCurrentWorkingDirectory across the repo" -> grep reveals 15 occurrences in 8 files
+- "Implement registration, catalog, cart, checkout" -> multiple complex features
+
+Skip it:
+- "How do I print Hello World in Python?" -> informational
+- "Add a comment to calculateTotal" -> single edit
+- "Run npm install and tell me what happened" -> one command
+
+When in doubt, use it.

package/src/tool/tool.ts

@@ -0,0 +1,183 @@
+import { PermissionV1 } from "@ac/core/v1/permission"
+import { Effect, Schema } from "effect"
+import { SessionV1 } from "@ac/core/v1/session"
+import type { JSONSchema7 } from "@ai-sdk/provider"
+import type { MessageV2 } from "../session/message-v2"
+import type { Permission } from "../permission"
+import type { SessionID, MessageID } from "../session/schema"
+import * as Truncate from "./truncate"
+import { Agent } from "@/agent/agent"
+
+interface Metadata {
+  [key: string]: any
+}
+
+// TODO: remove this hack
+export type DynamicDescription = (agent: Agent.Info) => Effect.Effect<string>
+
+/**
+ * Raised when the LLM calls a tool with arguments that fail the parameter
+ * schema. This is the canonical "rewrite the input" tool error: the typed
+ * error class makes it matchable upstream, and its `message` getter produces
+ * the model-facing prose that the AI SDK feeds back as the tool result.
+ */
+export class InvalidArgumentsError extends Schema.TaggedErrorClass<InvalidArgumentsError>()(
+  "ToolInvalidArgumentsError",
+  {
+    tool: Schema.String,
+    detail: Schema.String,
+  },
+) {
+  override get message() {
+    return `The ${this.tool} tool was called with invalid arguments: ${this.detail}.\nPlease rewrite the input so it satisfies the expected schema.`
+  }
+}
+
+export type Context<M extends Metadata = Metadata> = {
+  sessionID: SessionID
+  messageID: MessageID
+  agent: string
+  abort: AbortSignal
+  callID?: string
+  extra?: { [key: string]: unknown }
+  messages: SessionV1.WithParts[]
+  metadata(input: { title?: string; metadata?: M }): Effect.Effect<void>
+  ask(input: Omit<PermissionV1.Request, "id" | "sessionID" | "tool">): Effect.Effect<void>
+}
+
+export interface ExecuteResult<M extends Metadata = Metadata> {
+  title: string
+  metadata: M
+  output: string
+  attachments?: Omit<SessionV1.FilePart, "id" | "sessionID" | "messageID">[]
+}
+
+export interface Def<
+  Parameters extends Schema.Decoder<unknown> = Schema.Decoder<unknown>,
+  M extends Metadata = Metadata,
+> {
+  id: string
+  description: string
+  parameters: Parameters
+  jsonSchema?: JSONSchema7
+  execute(args: Schema.Schema.Type<Parameters>, ctx: Context): Effect.Effect<ExecuteResult<M>>
+  formatValidationError?(error: unknown): string
+}
+export type DefWithoutID<
+  Parameters extends Schema.Decoder<unknown> = Schema.Decoder<unknown>,
+  M extends Metadata = Metadata,
+> = Omit<Def<Parameters, M>, "id">
+
+export interface Info<
+  Parameters extends Schema.Decoder<unknown> = Schema.Decoder<unknown>,
+  M extends Metadata = Metadata,
+> {
+  id: string
+  init: () => Effect.Effect<DefWithoutID<Parameters, M>>
+}
+
+type Init<Parameters extends Schema.Decoder<unknown>, M extends Metadata> =
+  | DefWithoutID<Parameters, M>
+  | (() => Effect.Effect<DefWithoutID<Parameters, M>>)
+
+export type InferParameters<T> =
+  T extends Info<infer P, any>
+    ? Schema.Schema.Type<P>
+    : T extends Effect.Effect<Info<infer P, any>, any, any>
+      ? Schema.Schema.Type<P>
+      : never
+export type InferMetadata<T> =
+  T extends Info<any, infer M> ? M : T extends Effect.Effect<Info<any, infer M>, any, any> ? M : never
+
+export type InferDef<T> =
+  T extends Info<infer P, infer M>
+    ? Def<P, M>
+    : T extends Effect.Effect<Info<infer P, infer M>, any, any>
+      ? Def<P, M>
+      : never
+
+function wrap<Parameters extends Schema.Decoder<unknown>, Result extends Metadata>(
+  id: string,
+  init: Init<Parameters, Result>,
+  truncate: Truncate.Interface,
+  agents: Agent.Interface,
+) {
+  return () =>
+    Effect.gen(function* () {
+      const toolInfo = typeof init === "function" ? { ...(yield* init()) } : { ...init }
+      // Compile the parser closure once per tool init; `decodeUnknownEffect`
+      // allocates a new closure per call, so hoisting avoids re-closing it for
+      // every LLM tool invocation.
+      const decode = Schema.decodeUnknownEffect(toolInfo.parameters)
+      const execute = toolInfo.execute
+      toolInfo.execute = (args, ctx) => {
+        const attrs = {
+          "tool.name": id,
+          "session.id": ctx.sessionID,
+          "message.id": ctx.messageID,
+          ...(ctx.callID ? { "tool.call_id": ctx.callID } : {}),
+        }
+        return Effect.gen(function* () {
+          const decoded = yield* decode(args).pipe(
+            Effect.mapError(
+              (error) =>
+                new InvalidArgumentsError({
+                  tool: id,
+                  detail: toolInfo.formatValidationError ? toolInfo.formatValidationError(error) : String(error),
+                }),
+            ),
+          )
+          const result = yield* execute(decoded as Schema.Schema.Type<Parameters>, ctx)
+          if (result.metadata.truncated !== undefined) {
+            return result
+          }
+          const agent = yield* agents.get(ctx.agent)
+          const truncated = yield* truncate.output(result.output, {}, agent)
+          return {
+            ...result,
+            output: truncated.content,
+            metadata: {
+              ...result.metadata,
+              truncated: truncated.truncated,
+              ...(truncated.truncated && { outputPath: truncated.outputPath }),
+            },
+          }
+        }).pipe(Effect.orDie, Effect.withSpan("Tool.execute", { attributes: attrs }))
+      }
+      return toolInfo
+    })
+}
+
+export function define<
+  Parameters extends Schema.Decoder<unknown>,
+  Result extends Metadata,
+  R,
+  ID extends string = string,
+>(
+  id: ID,
+  init: Effect.Effect<Init<Parameters, Result>, never, R>,
+): Effect.Effect<Info<Parameters, Result>, never, R | Truncate.Service | Agent.Service> & { id: ID } {
+  return Object.assign(
+    Effect.gen(function* () {
+      const resolved = yield* init
+      const truncate = yield* Truncate.Service
+      const agents = yield* Agent.Service
+      return { id, init: wrap(id, resolved, truncate, agents) }
+    }),
+    { id },
+  )
+}
+
+export function init<P extends Schema.Decoder<unknown>, M extends Metadata>(
+  info: Info<P, M>,
+): Effect.Effect<Def<P, M>> {
+  return Effect.gen(function* () {
+    const init = yield* info.init()
+    return {
+      ...init,
+      id: info.id,
+    }
+  })
+}
+
+export * as Tool from "./tool"