lalph 0.3.37 → 0.3.39

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lalph",
   "type": "module",
-  "version": "0.3.37",
+  "version": "0.3.39",
   "publishConfig": {
     "access": "public"
   },
@@ -20,22 +20,24 @@
     "url": "https://github.com/tim-smart/lalph.git"
   },
   "devDependencies": {
-    "@changesets/changelog-github": "^0.5.2",
-    "@changesets/cli": "^2.29.8",
-    "@effect/language-service": "^0.75.1",
-    "@effect/platform-node": "4.0.0-beta.28",
-    "@linear/sdk": "^75.0.0",
+    "@changesets/changelog-github": "^0.6.0",
+    "@changesets/cli": "^2.30.0",
+    "@effect/ai-openai": "https://pkg.pr.new/Effect-TS/effect-smol/@effect/ai-openai@d440fd4",
+    "@effect/language-service": "^0.79.0",
+    "@effect/platform-node": "4.0.0-beta.29",
+    "@linear/sdk": "^76.0.0",
     "@octokit/plugin-rest-endpoint-methods": "^17.0.0",
     "@octokit/types": "^16.0.0",
-    "@typescript/native-preview": "7.0.0-dev.20260219.1",
+    "@typescript/native-preview": "7.0.0-dev.20260308.1",
+    "clanka": "^0.0.9",
     "concurrently": "^9.2.1",
-    "effect": "4.0.0-beta.28",
+    "effect": "4.0.0-beta.29",
     "husky": "^9.1.7",
-    "lint-staged": "^16.2.7",
+    "lint-staged": "^16.3.2",
     "octokit": "^5.0.5",
-    "oxlint": "^1.49.0",
+    "oxlint": "^1.51.0",
     "prettier": "^3.8.1",
-    "tsdown": "^0.20.3",
+    "tsdown": "^0.21.1",
     "typescript": "^5.9.3",
     "yaml": "^2.8.2"
   },

package/src/Clanka.ts

@@ -0,0 +1,46 @@
+import { Agent, OutputFormatter } from "clanka"
+import { Duration, Effect, Stream } from "effect"
+import {
+  TaskTools,
+  TaskToolsHandlers,
+  TaskToolsWithChoose,
+} from "./TaskTools.ts"
+import { clankaSubagent } from "./ClankaModels.ts"
+import { withStallTimeout } from "./shared/stream.ts"
+import type { AiError } from "effect/unstable/ai"
+import type { RunnerStalled } from "./domain/Errors.ts"
+
+export const runClanka = Effect.fnUntraced(
+  /** The working directory to run the agent in */
+  function* (options: {
+    readonly directory: string
+    readonly prompt: string
+    readonly system?: string | undefined
+    readonly stallTimeout?: Duration.Input | undefined
+    readonly withChoose?: boolean | undefined
+  }) {
+    const agent = yield* Agent.make({
+      ...options,
+      tools: options.withChoose
+        ? TaskToolsWithChoose
+        : (TaskTools as unknown as typeof TaskToolsWithChoose),
+      subagentModel: clankaSubagent,
+    })
+    let stream = options.stallTimeout
+      ? withStallTimeout(options.stallTimeout)(agent.output)
+      : agent.output
+
+    return yield* stream.pipe(
+      OutputFormatter.pretty,
+      Stream.runForEachArray((out) => {
+        for (const item of out) {
+          process.stdout.write(item)
+        }
+        return Effect.void
+      }),
+      (_) => _ as Effect.Effect<void, AiError.AiError | RunnerStalled>,
+    )
+  },
+  Effect.scoped,
+  Effect.provide([Agent.layerServices, TaskToolsHandlers]),
+)

package/src/ClankaModels.ts

@@ -0,0 +1,53 @@
+import { NodeHttpClient } from "@effect/platform-node"
+import { Codex } from "clanka"
+import { Layer, LayerMap, PlatformError, Schema } from "effect"
+import { layerKvs } from "./Kvs.ts"
+import { OpenAiClient, OpenAiLanguageModel } from "@effect/ai-openai"
+
+export const CodexLayer: Layer.Layer<
+  OpenAiClient.OpenAiClient,
+  PlatformError.PlatformError
+> = Codex.layer.pipe(
+  Layer.provide(NodeHttpClient.layerUndici),
+  Layer.provide(layerKvs),
+)
+
+export const clankaModels = {
+  "gpt-5.4-xhigh": OpenAiLanguageModel.model("gpt-5.4", {
+    reasoning: {
+      effort: "xhigh",
+      summary: "auto",
+    },
+  }).pipe(Layer.provideMerge(CodexLayer)),
+  "gpt-5.4-high": OpenAiLanguageModel.model("gpt-5.4", {
+    reasoning: {
+      effort: "high",
+      summary: "auto",
+    },
+  }).pipe(Layer.provideMerge(CodexLayer)),
+  "gpt-5.4-medium": OpenAiLanguageModel.model("gpt-5.4", {
+    reasoning: {
+      effort: "high",
+      summary: "auto",
+    },
+  }).pipe(Layer.provideMerge(CodexLayer)),
+} as const
+
+export type ClankaModel = keyof typeof clankaModels
+export const ClankaModel = Schema.Literals(
+  Object.keys(clankaModels) as ClankaModel[],
+)
+
+export const clankaSubagent = OpenAiLanguageModel.model("gpt-5.4", {
+  reasoning: {
+    effort: "low",
+    summary: "auto",
+  },
+}).pipe(Layer.provideMerge(CodexLayer))
+
+export class ClankaModels extends LayerMap.Service<ClankaModels>()(
+  "lalph/ClankaModels",
+  {
+    layers: clankaModels,
+  },
+) {}

package/src/GitFlow.ts

@@ -61,7 +61,7 @@ export const GitFlowPR = Layer.succeed(
     setupInstructions: ({ githubPrNumber }) =>
       githubPrNumber
         ? `The Github PR #${githubPrNumber} has been detected for this task and the branch has been checked out.
-   - Review feedback in the .lalph/feedback.md file (same folder as the prd.yml file).`
+   - Review feedback in the .lalph/feedback.md file.`
         : `Create a new branch for the task using the format \`{task id}/description\`, using the current HEAD as the base (don't checkout any other branches first).`,
 
     commitInstructions: (

package/src/IssueSource.ts

@@ -22,11 +22,11 @@ export class IssueSource extends ServiceMap.Service<
     readonly updateIssue: (options: {
       readonly projectId: ProjectId
       readonly issueId: string
-      readonly title?: string
-      readonly description?: string
-      readonly state?: PrdIssue["state"]
-      readonly blockedBy?: ReadonlyArray<string>
-      readonly autoMerge?: boolean
+      readonly title?: string | undefined
+      readonly description?: string | undefined
+      readonly state?: PrdIssue["state"] | undefined
+      readonly blockedBy?: ReadonlyArray<string> | undefined
+      readonly autoMerge?: boolean | undefined
     }) => Effect.Effect<void, IssueSourceError>
 
     readonly cancelIssue: (

package/src/Presets.ts

@@ -5,6 +5,7 @@ import { Prompt } from "effect/unstable/cli"
 import { allCliAgents, type AnyCliAgent } from "./domain/CliAgent.ts"
 import { parseCommand } from "./shared/child-process.ts"
 import { IssueSource } from "./IssueSource.ts"
+import { ClankaModel, clankaModels } from "./ClankaModels.ts"
 
 export const allCliAgentPresets = new Setting(
   "cliAgentPresets",
@@ -119,12 +120,29 @@ export const addOrUpdatePreset = Effect.fnUntraced(function* (options?: {
     options?.existing?.commandPrefix,
   )
 
+  const clankaModel = yield* Prompt.select<ClankaModel | undefined>({
+    message: "clanka model?",
+    choices: [
+      {
+        title: "none",
+        value: undefined,
+        selected: options?.existing?.clankaModel === undefined,
+      },
+      ...(Object.keys(clankaModels) as Array<ClankaModel>).map((key) => ({
+        title: key,
+        value: key,
+        selected: options?.existing?.clankaModel === key,
+      })),
+    ],
+  })
+
   let preset = new CliAgentPreset({
     id,
     cliAgent,
     commandPrefix,
     extraArgs,
     sourceMetadata: {},
+    ...(clankaModel ? { clankaModel } : {}),
   })
 
   if (id !== CliAgentPreset.defaultId) {

package/src/PromptGen.ts

@@ -39,28 +39,7 @@ prd.yml file with a new id for the task.
 
 After adding a new task, you can setup dependencies using the \`blockedBy\` field
 
-#### Task creation guidelines
-
-**Important**: When creating tasks, make sure each task is independently shippable
-without failing validation checks (typechecks, linting, tests). If a task would only
-pass validations when combined with another, combine the work into one task.
-
-Each task should be an atomic, committable piece of work.
-Instead of creating tasks like "Refactor the authentication system", create
-smaller tasks like "Implement OAuth2 login endpoint", "Add JWT token refresh mechanism", etc.${
-        options?.specsDirectory
-          ? `
-
-If you need to add a research task, mention in the description that it needs to:
-- add a specification file in the \`${options.specsDirectory}\` directory with
-  an implementation plan based on the research findings.
-- once the specification file is added, turn the implementation plan into tasks
-  in the prd.yml file. Each task should reference the specification file in its
-  description, and be small, atomic and independently shippable without failing
-  validation checks (typechecks, linting, tests).
-- make sure the follow up tasks include a dependency on the research task.`
-          : ""
-      }
+${taskGuidelines(options)}
 
 ### Removing tasks
 
@@ -103,6 +82,36 @@ The following instructions should be done without interaction or asking for perm
         options.gitFlow.requiresGithubPr
           ? `
 
+Set \`githubPrNumber\` to the PR number if one exists, otherwise use \`null\`.
+`
+          : "\n\nLeave `githubPrNumber` as null."
+      }
+`
+
+      const promptChooseClanka = (options: {
+        readonly gitFlow: GitFlow["Service"]
+      }) => `Your job is to choose the next task to work on from the current task list.
+**DO NOT** implement the task yet.
+
+The following instructions should be done without interaction or asking for permission.
+
+- Decide which single task to work on next from the task list. This should
+  be the task YOU decide as the most important to work on next, not just the
+  first task in the list.
+  - Only start tasks that are in a "todo" state.
+  - You **cannot** start tasks unless they have an empty \`blockedBy\` field.${
+    options.gitFlow.requiresGithubPr
+      ? `
+- Check if there is an open Github PR for the chosen task. If there is, note the PR number for inclusion in the task.json file.
+   - Only include "open" PRs that are not yet merged.
+   - The pull request will contain the task id in the title or description.`
+      : ""
+  }
+- Use the "chooseTask" function to select the task you have chosen.
+\`\`\`${
+        options.gitFlow.requiresGithubPr
+          ? `
+
 Set \`githubPrNumber\` to the PR number if one exists, otherwise use \`null\`.
 `
           : "\n\nLeave `githubPrNumber` as null."
@@ -139,6 +148,34 @@ challenges faced.
 
 ${prdNotes(options)}`
 
+      const systemClanka = (options: {
+        readonly specsDirectory: string
+      }) => `## Important: Adding new tasks
+
+**If at any point** you discover something that needs fixing, or another task
+that needs doing, immediately add it as a new task.
+
+## Important: Recording key information
+
+This session will time out after a certain period, so make sure to record
+key information that could speed up future work on the task in the description.
+Record the information **in the moment** as you discover it,
+do not wait until the end of the task. Things to record include:
+
+- Important discoveries about the codebase.
+- Any challenges faced and how you overcame them. For example:
+  - If it took multiple attempts to get something working, record what worked.
+  - If you found a library api was renamed or moved, record the new name.
+- Any other information that could help future work on similar tasks.
+
+## Handling blockers
+
+If for any reason you get stuck on a task, mark the task back as "todo" by updating its
+\`state\` and leaving some notes in the task's \`description\` field about the
+challenges faced.
+
+${taskGuidelines(options)}`
+
       const prompt = (options: {
         readonly task: PrdIssue
         readonly targetBranch: string | undefined
@@ -184,6 +221,49 @@ Your job is to implement the task described above.
 
 ${keyInformation(options)}`
 
+      const promptClanka = (options: {
+        readonly task: PrdIssue
+        readonly targetBranch: string | undefined
+        readonly specsDirectory: string
+        readonly githubPrNumber: number | undefined
+        readonly gitFlow: GitFlow["Service"]
+      }) => `# The task
+
+ID: ${options.task.id}
+Task: ${options.task.title}
+Description:
+
+${options.task.description}
+
+# Instructions
+
+Your job is to implement the task described above.
+
+1. Carefully study the current task list to understand the context of the task, and
+   discover any key learnings from previous work.
+   Also read the ${options.specsDirectory}/README.md file (if available), to see
+   if any previous specifications could assist you.
+2. ${options.gitFlow.setupInstructions(options)}
+3. Implement the task.
+   - If this task is a research task, **do not** make any code changes yet.
+   - If this task is a research task and you add follow-up tasks, include (at least) "${options.task.id}" in the new task's \`blockedBy\` field.
+   - **If at any point** you discover something that needs fixing, or another task
+     that needs doing, immediately add it as a new task unless you plan to fix it
+     as part of this task.
+   - Add important discoveries about the codebase, or challenges faced to the task's
+     \`description\`. More details below.
+4. Run any checks / feedback loops, such as type checks, unit tests, or linting.
+5. ${options.gitFlow.commitInstructions({
+        githubPrInstructions: sourceMeta.githubPrInstructions,
+        githubPrNumber: options.githubPrNumber,
+        taskId: options.task.id ?? "unknown",
+        targetBranch: options.targetBranch,
+      })}
+6. **After ${options.gitFlow.requiresGithubPr ? "pushing" : "committing"}**
+   your changes, update current task to reflect any changes in the task state.
+   - Rewrite the notes in the description to include only the key discoveries and information that could speed up future work on other tasks. Make sure to preserve important information such as specification file references.
+   - If you believe the task is complete, update the \`state\` to "in-review".`
+
       const promptReview = (options: {
         readonly prompt: string
         readonly gitFlow: GitFlow["Service"]
@@ -196,8 +276,7 @@ in your review, looking for any potential issues or improvements.
 Once you have completed your review, you should:
 
 - Make any code changes needed to fix issues you find.
-- Add follow-up tasks to the prd.yml file for any work that could not be done,
-  or for remaining issues that need addressing.
+- Add follow-up tasks for any work that could not be done, or for remaining issues that need addressing.
 
 ${options.gitFlow.reviewInstructions}
 
@@ -235,6 +314,25 @@ permission.
 
 ${prdNotes(options)}`
 
+      const promptTimeoutClanka = (options: {
+        readonly taskId: string
+        readonly specsDirectory: string
+      }) => `Your earlier attempt to complete the task with id \`${options.taskId}\` took too
+long and has timed out.
+
+The following instructions should be done without interaction or asking for
+permission.
+
+1. Investigate why you think the task took too long. Research the codebase
+   further to understand what is needed to complete the task.
+2. Mark the original task as "done" by updating its \`state\`.
+3. Break down the task into smaller tasks and add them to the prd.yml file.
+   Read the "### Adding tasks" section below **extremely carefully** for guidelines on creating tasks.
+4. Setup task dependencies using the \`blockedBy\` field as needed. You will need
+   to wait 5 seconds after adding tasks to the prd.yml file to allow the system
+   to assign ids to the new tasks before you can setup dependencies.
+5. If any specifications need updating based on your new understanding, update them.`
+
       const planPrompt = (options: {
         readonly plan: string
         readonly specsDirectory: string
@@ -321,12 +419,16 @@ ${prdNotes(options)}`
 
       return {
         promptChoose,
+        promptChooseClanka,
         prompt,
+        promptClanka,
         promptReview,
         promptReviewCustom,
         promptTimeout,
+        promptTimeoutClanka,
         planPrompt,
         promptPlanTasks,
+        systemClanka,
       } as const
     }),
   },
@@ -335,3 +437,28 @@ ${prdNotes(options)}`
     Layer.provide(CurrentIssueSource.layer),
   )
 }
+
+const taskGuidelines = (options?: {
+  readonly specsDirectory?: string | undefined
+}) => `#### Task creation guidelines
+
+**Important**: When creating tasks, make sure each task is independently shippable
+without failing validation checks (typechecks, linting, tests). If a task would only
+pass validations when combined with another, combine the work into one task.
+
+Each task should be an atomic, committable piece of work.
+Instead of creating tasks like "Refactor the authentication system", create
+smaller tasks like "Implement OAuth2 login endpoint", "Add JWT token refresh mechanism", etc.${
+  options?.specsDirectory
+    ? `
+
+If you need to add a research task, mention in the description that it needs to:
+- add a specification file in the \`${options.specsDirectory}\` directory with
+  an implementation plan based on the research findings.
+- once the specification file is added, turn the implementation plan into tasks
+  in the prd.yml file. Each task should reference the specification file in its
+  description, and be small, atomic and independently shippable without failing
+  validation checks (typechecks, linting, tests).
+- make sure the follow up tasks include a dependency on the research task.`
+    : ""
+}`

package/src/TaskTools.ts

@@ -0,0 +1,142 @@
+import { Deferred, Effect, Schema, ServiceMap, Struct } from "effect"
+import { Tool, Toolkit } from "effect/unstable/ai"
+import { PrdIssue } from "./domain/PrdIssue.ts"
+import { IssueSource } from "./IssueSource.ts"
+import { CurrentProjectId } from "./Settings.ts"
+
+export class ChosenTaskDeferred extends ServiceMap.Reference(
+  "lalph/TaskTools/ChosenTaskDeferred",
+  {
+    defaultValue: Deferred.makeUnsafe<{
+      readonly taskId: string
+      readonly githubPrNumber?: number | undefined
+    }>,
+  },
+) {}
+
+export class TaskTools extends Toolkit.make(
+  Tool.make("listTasks", {
+    description: "Returns the current list of tasks.",
+    success: Schema.Array(
+      Schema.Struct({
+        id: Schema.String.annotate({
+          documentation: "The unique identifier of the task.",
+        }),
+        ...Struct.pick(PrdIssue.fields, [
+          "title",
+          "description",
+          "state",
+          "priority",
+          "estimate",
+          "blockedBy",
+        ]),
+      }),
+    ),
+    dependencies: [CurrentProjectId],
+  }),
+  Tool.make("createTask", {
+    description: "Create a new task and return it's id.",
+    parameters: Schema.Struct({
+      title: Schema.String,
+      description: PrdIssue.fields.description,
+      state: PrdIssue.fields.state,
+      priority: PrdIssue.fields.priority,
+      estimate: PrdIssue.fields.estimate,
+      blockedBy: PrdIssue.fields.blockedBy,
+    }),
+    success: Schema.String,
+    dependencies: [CurrentProjectId],
+  }),
+  Tool.make("updateTask", {
+    description: "Update a task. Supports partial updates",
+    parameters: Schema.Struct({
+      taskId: Schema.String,
+      title: Schema.optional(PrdIssue.fields.title),
+      description: Schema.optional(PrdIssue.fields.description),
+      state: Schema.optional(PrdIssue.fields.state),
+      blockedBy: Schema.optional(PrdIssue.fields.blockedBy),
+    }),
+    dependencies: [CurrentProjectId],
+  }),
+  // Tool.make("removeTask", {
+  //   description: "Remove a task by it's id.",
+  //   parameters: Schema.String.annotate({
+  //     identifier: "taskId",
+  //   }),
+  //   dependencies: [CurrentProjectId],
+  // }),
+) {}
+
+export class TaskToolsWithChoose extends Toolkit.merge(
+  TaskTools,
+  Toolkit.make(
+    Tool.make("chooseTask", {
+      description: "Choose the task to work on",
+      parameters: Schema.Struct({
+        taskId: Schema.String,
+        githubPrNumber: Schema.optional(Schema.Number),
+      }),
+    }),
+  ),
+) {}
+
+export const TaskToolsHandlers = TaskToolsWithChoose.toLayer(
+  Effect.gen(function* () {
+    const source = yield* IssueSource
+
+    return TaskToolsWithChoose.of({
+      listTasks: Effect.fn("TaskTools.listTasks")(function* () {
+        yield* Effect.log(`Calling "listTasks"`)
+        const projectId = yield* CurrentProjectId
+        const tasks = yield* source.issues(projectId)
+        return tasks.map((issue) => ({
+          id: issue.id ?? "",
+          title: issue.title,
+          description: issue.description,
+          state: issue.state,
+          priority: issue.priority,
+          estimate: issue.estimate,
+          blockedBy: issue.blockedBy,
+        }))
+      }, Effect.orDie),
+      chooseTask: Effect.fn("TaskTools.chooseTask")(function* (options) {
+        yield* Effect.log(`Calling "chooseTask"`).pipe(
+          Effect.annotateLogs(options),
+        )
+        const deferred = yield* ChosenTaskDeferred
+        yield* Deferred.succeed(deferred, options)
+      }),
+      createTask: Effect.fn("TaskTools.createTask")(function* (options) {
+        yield* Effect.log(`Calling "createTask"`)
+        const projectId = yield* CurrentProjectId
+        const taskId = yield* source.createIssue(
+          projectId,
+          new PrdIssue({
+            ...options,
+            id: null,
+            autoMerge: false,
+          }),
+        )
+        return taskId.id
+      }, Effect.orDie),
+      updateTask: Effect.fn("TaskTools.updateTask")(function* (options) {
+        yield* Effect.log(`Calling "updateTask"`).pipe(
+          Effect.annotateLogs({ taskId: options.taskId }),
+        )
+        const projectId = yield* CurrentProjectId
+        yield* source.updateIssue({
+          projectId,
+          issueId: options.taskId,
+          ...options,
+        })
+      }, Effect.orDie),
+      // removeTask: Effect.fn("TaskTools.removeTask")(function* (taskId) {
+      //   yield* Effect.log(`Calling "removeTask"`).pipe(
+      //     Effect.annotateLogs({ taskId }),
+      //   )
+      //   const projectId = yield* CurrentProjectId
+      //   yield* source.cancelIssue(projectId, taskId)
+      // }, Effect.orDie),
+    })
+  }),
+)

package/src/Worktree.ts

@@ -1,6 +1,5 @@
 import {
   Chunk,
-  DateTime,
   Duration,
   Effect,
   FileSystem,
@@ -15,7 +14,6 @@ import {
   Stream,
 } from "effect"
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
-import { RunnerStalled } from "./domain/Errors.ts"
 import type { AnyCliAgent } from "./domain/CliAgent.ts"
 import { constWorkerMaxOutputChunks, CurrentWorkerState } from "./Workers.ts"
 import { AtomRegistry } from "effect/unstable/reactivity"
@@ -23,6 +21,7 @@ import { CurrentProjectId } from "./Settings.ts"
 import { projectById } from "./Projects.ts"
 import { parseBranch } from "./shared/git.ts"
 import { resolveLalphDirectory } from "./shared/lalphDirectory.ts"
+import { withStallTimeout } from "./shared/stream.ts"
 
 export class Worktree extends ServiceMap.Service<Worktree>()("lalph/Worktree", {
   make: Effect.gen(function* () {
@@ -255,23 +254,6 @@ const makeExecHelpers = Effect.fnUntraced(function* (options: {
     Effect.fnUntraced(function* (command: ChildProcess.Command) {
       const registry = yield* AtomRegistry.AtomRegistry
       const worker = yield* CurrentWorkerState
-      let lastOutputAt = yield* DateTime.now
-
-      const stallTimeout = Effect.suspend(function loop(): Effect.Effect<
-        never,
-        RunnerStalled
-      > {
-        const now = DateTime.nowUnsafe()
-        const deadline = DateTime.addDuration(
-          lastOutputAt,
-          options.stallTimeout,
-        )
-        if (DateTime.isLessThan(deadline, now)) {
-          return Effect.fail(new RunnerStalled())
-        }
-        const timeUntilDeadline = DateTime.distance(deadline, now)
-        return Effect.flatMap(Effect.sleep(timeUntilDeadline), loop)
-      })
 
       const handle = yield* provide(command.asEffect())
 
@@ -280,8 +262,8 @@ const makeExecHelpers = Effect.fnUntraced(function* (options: {
         options.cliAgent.outputTransformer
           ? options.cliAgent.outputTransformer
           : identity,
+        withStallTimeout(options.stallTimeout),
         Stream.runForEachArray((output) => {
-          lastOutputAt = DateTime.nowUnsafe()
           for (const chunk of output) {
             process.stdout.write(chunk)
           }
@@ -294,7 +276,6 @@ const makeExecHelpers = Effect.fnUntraced(function* (options: {
           )
           return Effect.void
         }),
-        Effect.raceFirst(stallTimeout),
       )
       return yield* handle.exitCode
     }, Effect.scoped)