@llm4ts/flow 0.1.0

package/src/GitTool.ts

@@ -0,0 +1,214 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { Capabilities, type Capability } from "@llm4ts/core/Capability"
+import type { ProcessExecutorShape, ProcessResult } from "@llm4ts/core/ProcessExecutor"
+import { ProcessError, type FlowError } from "./FlowError.ts"
+import type { FlowEventsShape } from "./FlowEvents.ts"
+import { guarded } from "./CapabilityGuard.ts"
+
+export class BranchCreated extends Schema.TaggedClass<BranchCreated>()("Created", {}) {}
+export class BranchAlreadyExists extends Schema.TaggedClass<BranchAlreadyExists>()(
+  "AlreadyExists",
+  {}
+) {}
+export const CreateBranch = Schema.Union([BranchCreated, BranchAlreadyExists])
+export type CreateBranch = typeof CreateBranch.Type
+
+export class Committed extends Schema.TaggedClass<Committed>()("Committed", {}) {}
+export class NothingToCommit extends Schema.TaggedClass<NothingToCommit>()("NothingToCommit", {}) {}
+export const CommitResult = Schema.Union([Committed, NothingToCommit])
+export type CommitResult = typeof CommitResult.Type
+
+export interface GitToolShape {
+  readonly init: Effect.Effect<void, FlowError>
+  readonly initBare: Effect.Effect<void, FlowError>
+  readonly config: (key: string, value: string) => Effect.Effect<void, FlowError>
+  readonly status: Effect.Effect<string, FlowError>
+  readonly currentBranch: Effect.Effect<string, FlowError>
+  readonly diff: Effect.Effect<string, FlowError>
+  readonly diffAll: Effect.Effect<string, FlowError>
+  readonly defaultBase: Effect.Effect<string, FlowError>
+  readonly diffVsBase: (base: string, threeDot?: boolean) => Effect.Effect<string, FlowError>
+  readonly changedFilesVsBase: (
+    base: string,
+    threeDot?: boolean
+  ) => Effect.Effect<ReadonlyArray<string>, FlowError>
+  readonly addRemote: (name: string, url: string) => Effect.Effect<void, FlowError>
+  readonly checkout: (name: string) => Effect.Effect<void, FlowError>
+  readonly checkoutOrCreate: (name: string) => Effect.Effect<void, FlowError>
+  readonly createBranch: (name: string) => Effect.Effect<CreateBranch, FlowError>
+  readonly commitAll: (message: string) => Effect.Effect<CommitResult, FlowError>
+  readonly push: (remote: string, branch: string) => Effect.Effect<void, FlowError>
+  readonly checkpoint: Effect.Effect<string, FlowError>
+  readonly rollback: (checkpoint: string) => Effect.Effect<void, FlowError>
+  readonly addWorktree: (path: string, branch: string) => Effect.Effect<void, FlowError>
+  readonly removeWorktree: (path: string) => Effect.Effect<void, FlowError>
+}
+
+const nonInteractiveEnvironment = Object.freeze({
+  GIT_TERMINAL_PROMPT: "0",
+  GIT_SSH_COMMAND: "ssh -o BatchMode=yes"
+})
+
+const text = (lines: ReadonlyArray<string>): string => lines.join("\n").trim()
+
+const problem = (result: ProcessResult): string => {
+  const detail = text([...result.stdout, ...result.stderr])
+  return detail.length === 0 ? `process exited with code ${result.exitCode}` : detail
+}
+
+export const makeGitTool = (
+  process: ProcessExecutorShape,
+  workDir: string,
+  events: FlowEventsShape
+): GitToolShape => {
+  const run = (args: ReadonlyArray<string>): Effect.Effect<ProcessResult, FlowError> =>
+    process.run(["git", ...args], workDir, nonInteractiveEnvironment).pipe(
+      Effect.mapError((error) =>
+        ProcessError.make({
+          message: `git ${args.join(" ")}`,
+          detail: error.message
+        })
+      )
+    )
+
+  const runOrFail = (args: ReadonlyArray<string>): Effect.Effect<string, FlowError> =>
+    Effect.flatMap(run(args), (result) =>
+      result.exitCode === 0
+        ? Effect.succeed(text(result.stdout))
+        : Effect.fail(
+            ProcessError.make({
+              message: `git ${args.join(" ")}`,
+              detail: problem(result)
+            })
+          )
+    )
+
+  const gate = <A>(
+    capability: Capability,
+    operation: string,
+    effect: Effect.Effect<A, FlowError>
+  ): Effect.Effect<A, FlowError> => guarded(capability, operation, events, effect)
+
+  const write = <A>(
+    operation: string,
+    effect: Effect.Effect<A, FlowError>
+  ): Effect.Effect<A, FlowError> => gate(Capabilities.GitWrite, operation, effect)
+
+  const read = <A>(
+    operation: string,
+    effect: Effect.Effect<A, FlowError>
+  ): Effect.Effect<A, FlowError> => gate(Capabilities.GitRead, operation, effect)
+
+  const createBranch = (name: string): Effect.Effect<CreateBranch, FlowError> =>
+    write(
+      "git checkout -b",
+      Effect.flatMap(
+        run(["checkout", "-b", name]),
+        (result): Effect.Effect<CreateBranch, FlowError> =>
+          result.exitCode === 0
+            ? Effect.succeed(new BranchCreated())
+            : text(result.stderr).includes("already exists")
+              ? Effect.succeed(new BranchAlreadyExists())
+              : Effect.fail(
+                  ProcessError.make({
+                    message: `git checkout -b ${name}`,
+                    detail: problem(result)
+                  })
+                )
+      )
+    )
+
+  const checkout = (name: string): Effect.Effect<void, FlowError> =>
+    write("git checkout", runOrFail(["checkout", name]).pipe(Effect.asVoid))
+
+  const addAll = runOrFail(["add", "-A"]).pipe(Effect.asVoid)
+
+  const commitAllEffect = (message: string): Effect.Effect<CommitResult, FlowError> =>
+    Effect.gen(function* () {
+      yield* addAll
+      const result = yield* run(["commit", "-m", message])
+      if (result.exitCode === 0) {
+        return new Committed()
+      }
+      if (problem(result).includes("nothing to commit")) {
+        return new NothingToCommit()
+      }
+      return yield* ProcessError.make({
+        message: "git commit",
+        detail: problem(result)
+      })
+    })
+
+  return {
+    init: write(
+      "git init",
+      runOrFail(["-c", "init.defaultBranch=main", "init"]).pipe(Effect.asVoid)
+    ),
+    initBare: write(
+      "git init --bare",
+      runOrFail(["-c", "init.defaultBranch=main", "init", "--bare"]).pipe(Effect.asVoid)
+    ),
+    config: (key, value) =>
+      write("git config", runOrFail(["config", key, value]).pipe(Effect.asVoid)),
+    status: read("git status", runOrFail(["status", "--short"])),
+    currentBranch: read("git currentBranch", runOrFail(["rev-parse", "--abbrev-ref", "HEAD"])),
+    diff: read("git diff", runOrFail(["diff"])),
+    diffAll: read(
+      "git diffAll",
+      runOrFail(["add", "--intent-to-add", "-A"]).pipe(Effect.andThen(runOrFail(["diff"])))
+    ),
+    defaultBase: read(
+      "git defaultBase",
+      Effect.flatMap(run(["symbolic-ref", "refs/remotes/origin/HEAD"]), (symbolic) => {
+        const value = text(symbolic.stdout)
+        if (symbolic.exitCode === 0 && value.length > 0) {
+          return Effect.succeed(value.replace(/^refs\/remotes\//, ""))
+        }
+        return Effect.flatMap(run(["rev-parse", "--verify", "--quiet", "origin/main"]), (main) =>
+          main.exitCode === 0
+            ? Effect.succeed("origin/main")
+            : run(["rev-parse", "--verify", "--quiet", "origin/master"]).pipe(
+                Effect.map((master) => (master.exitCode === 0 ? "origin/master" : "main"))
+              )
+        )
+      })
+    ),
+    diffVsBase: (base, threeDot = true) =>
+      read("git diffVsBase", runOrFail(["diff", `${base}${threeDot ? "..." : ".."}HEAD`])),
+    changedFilesVsBase: (base, threeDot = true) =>
+      read(
+        "git changedFilesVsBase",
+        runOrFail(["diff", "--name-only", `${base}${threeDot ? "..." : ".."}HEAD`]).pipe(
+          Effect.map((output) =>
+            output
+              .split(/\r?\n/)
+              .map((line) => line.trim())
+              .filter((line) => line.length > 0)
+          )
+        )
+      ),
+    addRemote: (name, url) =>
+      write("git addRemote", runOrFail(["remote", "add", name, url]).pipe(Effect.asVoid)),
+    checkout,
+    createBranch,
+    checkoutOrCreate: (name) =>
+      Effect.flatMap(createBranch(name), (created) =>
+        created._tag === "Created" ? Effect.void : checkout(name)
+      ),
+    commitAll: (message) => write("git commitAll", commitAllEffect(message)),
+    push: (remote, branch) =>
+      gate(
+        Capabilities.GitPush,
+        "git push",
+        runOrFail(["push", "-u", remote, branch]).pipe(Effect.asVoid)
+      ),
+    checkpoint: read("git checkpoint", runOrFail(["rev-parse", "HEAD"])),
+    rollback: (checkpoint) =>
+      write("git rollback", runOrFail(["reset", "--hard", checkpoint]).pipe(Effect.asVoid)),
+    addWorktree: (path, branch) =>
+      write("git worktree add", runOrFail(["worktree", "add", path, branch]).pipe(Effect.asVoid)),
+    removeWorktree: (path) =>
+      write("git worktree remove", runOrFail(["worktree", "remove", path]).pipe(Effect.asVoid))
+  }
+}

package/src/Interaction.ts

@@ -0,0 +1,23 @@
+import type * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { FlowError } from "./FlowError.ts"
+
+export interface InteractionShape {
+  readonly ask: (question: string) => Effect.Effect<string, FlowError>
+}
+
+export class ApprovalAllowed extends Schema.TaggedClass<ApprovalAllowed>()("Allow", {}) {}
+
+export class ApprovalDenied extends Schema.TaggedClass<ApprovalDenied>()("Deny", {
+  reason: Schema.String
+}) {}
+
+export const ApprovalDecision = Schema.Union([ApprovalAllowed, ApprovalDenied])
+export type ApprovalDecision = typeof ApprovalDecision.Type
+
+export interface ApprovalPolicy {
+  readonly decide: (
+    toolName: string,
+    input: Schema.Json
+  ) => Effect.Effect<ApprovalDecision, FlowError>
+}

package/src/McpServer.ts

@@ -0,0 +1,168 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { FlowError } from "./FlowError.ts"
+import { ApprovalAllowed, type ApprovalPolicy, type InteractionShape } from "./Interaction.ts"
+
+export interface McpTool {
+  readonly name: string
+  readonly description: string
+  readonly inputSchema: Schema.Json
+  readonly call: (arguments_: Schema.Json) => Effect.Effect<string, FlowError>
+}
+
+export const McpProtocolVersion = "2025-06-18"
+export const McpServerName = "llm4ts"
+export const McpServerVersion = "1.0"
+
+const objectField = (value: Schema.Json, name: string): Schema.Json | undefined => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined
+  }
+  const field = Reflect.get(value, name)
+  return Schema.is(Schema.Json)(field) ? field : undefined
+}
+
+const stringField = (value: Schema.Json, name: string): string | undefined => {
+  const field = objectField(value, name)
+  return typeof field === "string" ? field : undefined
+}
+
+const params = (request: Schema.Json): Schema.Json => objectField(request, "params") ?? {}
+
+const result = (id: Schema.Json, value: Schema.Json): Schema.Json => ({
+  jsonrpc: "2.0",
+  id,
+  result: value
+})
+
+const error = (id: Schema.Json, code: number, message: string): Schema.Json => ({
+  jsonrpc: "2.0",
+  id,
+  error: { code, message }
+})
+
+const toolContent = (text: string, isError: boolean): Schema.Json => ({
+  content: [{ type: "text", text }],
+  isError
+})
+
+export const askUserTool = (interaction: InteractionShape): McpTool => ({
+  name: "ask_user",
+  description:
+    "Ask the human operator a question and wait for their answer. Use when a decision or clarification is required.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      question: {
+        type: "string",
+        description: "The question to put to the human operator."
+      }
+    },
+    required: ["question"]
+  },
+  call: (arguments_) => interaction.ask(stringField(arguments_, "question") ?? "")
+})
+
+export const approvalTool = (policy: ApprovalPolicy): McpTool => ({
+  name: "approve",
+  description:
+    "Decide whether the agent may run a pending tool call and return its permission verdict.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      tool_name: { type: "string" },
+      input: { type: "object" }
+    },
+    required: ["tool_name"]
+  },
+  call: (arguments_) => {
+    const input = objectField(arguments_, "input") ?? {}
+    return policy
+      .decide(stringField(arguments_, "tool_name") ?? "", input)
+      .pipe(
+        Effect.map((decision) =>
+          JSON.stringify(
+            decision instanceof ApprovalAllowed
+              ? { behavior: "allow", updatedInput: input }
+              : { behavior: "deny", message: decision.reason }
+          )
+        )
+      )
+  }
+})
+
+const initializeResult = (request: Schema.Json): Schema.Json => ({
+  protocolVersion: stringField(params(request), "protocolVersion") ?? McpProtocolVersion,
+  capabilities: { tools: {} },
+  serverInfo: {
+    name: McpServerName,
+    version: McpServerVersion
+  }
+})
+
+const toolsListResult = (tools: ReadonlyArray<McpTool>): Schema.Json => ({
+  tools: tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema
+  }))
+})
+
+const toolsCall = (
+  id: Schema.Json,
+  request: Schema.Json,
+  tools: ReadonlyArray<McpTool>
+): Effect.Effect<Schema.Json> => {
+  const requestParams = params(request)
+  const name = stringField(requestParams, "name") ?? ""
+  const tool = tools.find((candidate) => candidate.name === name)
+  if (tool === undefined) {
+    return Effect.succeed(error(id, -32602, `unknown tool: ${name}`))
+  }
+  return Effect.result(tool.call(objectField(requestParams, "arguments") ?? {})).pipe(
+    Effect.map((outcome) =>
+      outcome._tag === "Success"
+        ? result(id, toolContent(outcome.success, false))
+        : result(id, toolContent(`tool '${name}' failed: ${outcome.failure.message}`, true))
+    )
+  )
+}
+
+export const handleMcpRequest = Effect.fn("@llm4ts/flow/McpServer.handle")(function* (
+  request: Schema.Json,
+  tools: ReadonlyArray<McpTool>
+): Effect.fn.Return<Schema.Json | undefined> {
+  const id = objectField(request, "id")
+  if (id === undefined) {
+    return undefined
+  }
+  switch (stringField(request, "method") ?? "") {
+    case "initialize":
+      return result(id, initializeResult(request))
+    case "tools/list":
+      return result(id, toolsListResult(tools))
+    case "tools/call":
+      return yield* toolsCall(id, request, tools)
+    default:
+      return error(id, -32601, `method not found: ${stringField(request, "method") ?? ""}`)
+  }
+})
+
+const parseError = (): Schema.Json => ({
+  jsonrpc: "2.0",
+  id: null,
+  error: { code: -32700, message: "Parse error" }
+})
+
+export const handleMcpLine = (
+  line: string,
+  tools: ReadonlyArray<McpTool>
+): Effect.Effect<string | undefined> => {
+  const parsed = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Json))(line)
+  if (parsed._tag === "None") {
+    return Effect.succeed(JSON.stringify(parseError()))
+  }
+  return handleMcpRequest(parsed.value, tools).pipe(
+    Effect.map((response) => (response === undefined ? undefined : JSON.stringify(response)))
+  )
+}

package/src/Mermaid.ts

@@ -0,0 +1,112 @@
+import { StageCompleted, StageFailed, StageStarted, type FlowEvent } from "./FlowEvents.ts"
+import type { TraceLine } from "./FlowRecorder.ts"
+
+const escapeLabel = (label: string): string => label.replaceAll('"', "'")
+
+export const renderMermaid = (events: ReadonlyArray<FlowEvent>): string => {
+  const starts = events
+    .filter((event): event is StageStarted => event._tag === "StageStarted")
+    .map((event) => event.stage)
+  const failed = new Set(
+    events
+      .filter((event): event is StageFailed => event._tag === "StageFailed")
+      .map((event) => event.stage)
+  )
+  if (starts.length === 0) {
+    return 'flowchart TD\n  none["(no stages)"]'
+  }
+  const order = [...new Set(starts)]
+  const counts = new Map<string, number>()
+  for (const stage of starts) {
+    counts.set(stage, (counts.get(stage) ?? 0) + 1)
+  }
+  const ids = new Map<string, string>()
+  order.forEach((name, index) => ids.set(name, `n${index}`))
+  const nodes = order.map((name) => {
+    const count = counts.get(name) ?? 1
+    const label = count > 1 ? `${name} ×${count}` : name
+    return `  ${ids.get(name)}["${escapeLabel(label)}"]${failed.has(name) ? ":::failed" : ""}`
+  })
+  const edges = order
+    .slice(1)
+    .map((name, index) => `  ${ids.get(order[index] ?? "")} --> ${ids.get(name)}`)
+  const styles = failed.size === 0 ? [] : ["  classDef failed fill:#fdd,stroke:#c00,color:#900;"]
+  return ["flowchart TD", ...nodes, ...edges, ...styles].join("\n")
+}
+
+const traceStage = (line: TraceLine): FlowEvent | undefined => {
+  const field = (key: string): string | undefined => {
+    const direct = line.fields[key]
+    if (typeof direct === "string") {
+      return direct
+    }
+    const encoded = line.fields.event
+    if (typeof encoded !== "string") {
+      return undefined
+    }
+    try {
+      const event: unknown = JSON.parse(encoded)
+      if (typeof event !== "object" || event === null) {
+        return undefined
+      }
+      const value = Reflect.get(event, key)
+      return typeof value === "string" ? value : undefined
+    } catch {
+      return undefined
+    }
+  }
+  switch (line.kind) {
+    case "StageStarted": {
+      const stage = field("stage")
+      return stage === undefined ? undefined : StageStarted.make({ stage })
+    }
+    case "StageCompleted": {
+      const stage = field("stage")
+      return stage === undefined ? undefined : StageCompleted.make({ stage })
+    }
+    case "StageFailed": {
+      const stage = field("stage")
+      return stage === undefined
+        ? undefined
+        : StageFailed.make({ stage, message: field("message") ?? "" })
+    }
+    default:
+      return undefined
+  }
+}
+
+export const renderMermaidTrace = (lines: ReadonlyArray<TraceLine>): string =>
+  renderMermaid(
+    lines.flatMap((line) => {
+      const event = traceStage(line)
+      return event === undefined ? [] : [event]
+    })
+  )
+
+const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+
+const base64Url = (value: string): string => {
+  const bytes = new TextEncoder().encode(value)
+  let encoded = ""
+  for (let index = 0; index < bytes.length; index += 3) {
+    const first = bytes[index] ?? 0
+    const second = bytes[index + 1]
+    const third = bytes[index + 2]
+    const block = (first << 16) | ((second ?? 0) << 8) | (third ?? 0)
+    encoded += alphabet[(block >> 18) & 63]
+    encoded += alphabet[(block >> 12) & 63]
+    if (second !== undefined) {
+      encoded += alphabet[(block >> 6) & 63]
+    }
+    if (third !== undefined) {
+      encoded += alphabet[block & 63]
+    }
+  }
+  return encoded
+}
+
+export const mermaidLiveUrl = (diagram: string): string =>
+  `https://mermaid.ink/svg/${base64Url(diagram)}`
+
+export const mermaidDocument = (diagram: string): string =>
+  `\`\`\`mermaid\n${diagram}\n\`\`\`\n\n[View on mermaid.ink](${mermaidLiveUrl(diagram)})\n`