@alecsibilia/luca 14.0.0-alpha.2 → 14.0.0-alpha.21

package/engine/guards/guard-roles.ts

@@ -0,0 +1,68 @@
+/**
+ * The guard's roles: which role each agent plays by, the tools each sees, and
+ * the shape of a guard decision.
+ */
+import { z } from 'zod'
+
+import type { AgentRole } from '../agents/role-results'
+
+/**
+ * The roles the **guard** knows. `reviewer` covers every reviewer (the ticket
+ * reviewer and the final review's lenses). The learner has no agent
+ * role yet (#370) but its rules are here already.
+ */
+export const GuardRoleSchema = z.enum([
+    'test-writer',
+    'implementer',
+    'reviewer',
+    'learner',
+])
+
+export type GuardRole = z.infer<typeof GuardRoleSchema>
+
+const GUARD_ROLE_OF: Record<AgentRole, GuardRole> = {
+    'test-writer': 'test-writer',
+    implementer: 'implementer',
+    'ticket-reviewer': 'reviewer',
+    'architecture-lens': 'reviewer',
+    'simplification-lens': 'reviewer',
+    'security-lens': 'reviewer',
+    'integration-lens': 'reviewer',
+    'rules-lens': 'reviewer',
+    learner: 'learner',
+}
+
+/** The guard role an agent role plays by. */
+export const guardRoleOf = ({ role }: { role: AgentRole }): GuardRole =>
+    GUARD_ROLE_OF[role]
+
+/** Whether a guard role may change files at all. */
+export const isWriter = (role: GuardRole): boolean =>
+    role === 'test-writer' || role === 'implementer'
+
+/** What the guard says about one tool call. */
+export type ToolDecision = { allow: true } | { allow: false; reason: string }
+
+export const ALLOW: ToolDecision = { allow: true }
+
+export const deny = (reason: string): ToolDecision => ({ allow: false, reason })
+
+/** The rules an agent's guards check it against: its role, and whether it may edit tests. */
+export type GuardArgs = {
+    role: GuardRole
+    /**
+     * Whether this agent may edit test files: true for the test-writer and a
+     * refactor ticket's implementer. A test-writer without it writes nothing;
+     * a reviewer or the learner never writes, whatever it says.
+     */
+    may_edit_tests: boolean
+}
+
+export const READ_TOOLS = ['Read', 'Grep', 'Glob']
+
+export const TOOLS: Record<GuardRole, string[]> = {
+    'test-writer': ['Read', 'Grep', 'Glob', 'Edit', 'Write', 'Bash'],
+    implementer: ['Read', 'Grep', 'Glob', 'Edit', 'Write', 'Bash'],
+    reviewer: ['Read', 'Grep', 'Glob', 'Bash'],
+    learner: ['Read', 'Grep', 'Glob'],
+}

package/engine/guards/helper-rules.ts

@@ -0,0 +1,92 @@
+/**
+ * Pure: the rules for **helpers** (#627), the read-only Haiku sessions an
+ * agent may start with the SDK's `Agent` tool to search the repo.
+ */
+import { z } from 'zod'
+
+import { ALLOW, deny, READ_TOOLS, type ToolDecision } from './guard-roles'
+
+/** The SDK tool that starts a helper. */
+export const HELPER_TOOL = 'Agent'
+
+/** The one helper type an agent may start. */
+export const HELPER_TYPE = 'searcher'
+
+/** Helpers always run on the newest Haiku, by its short name. */
+export const HELPER_MODEL = 'haiku'
+
+/** The only tools a helper has: it reads and searches, nothing else. */
+export const HELPER_TOOLS = READ_TOOLS
+
+/** How many helpers one agent may have running at once. */
+export const MAX_HELPERS = 3
+
+/** The `searcher` helper's definition, for the SDK's `agents` option. */
+export const SEARCHER = {
+    description:
+        'A read-only helper that searches the repo: finds files, symbols and callers, and reports what it found. It cannot edit files or run commands.',
+    model: HELPER_MODEL,
+    tools: [...HELPER_TOOLS],
+    prompt: 'You are a read-only searcher. You may only read and search files in the current worktree with Read, Grep and Glob. Never try to change a file or run a command. Answer with what you found: file paths, line numbers and short excerpts, as briefly as the question allows.',
+}
+
+const HelperInputSchema = z.object({
+    subagent_type: z.string().optional(),
+    model: z.string().optional(),
+    run_in_background: z.boolean().optional(),
+    isolation: z.string().optional(),
+})
+
+/**
+ * The guard's decision for an `Agent` call that starts a helper, apart from
+ * how many already run. Only a `searcher`, on Haiku (never a Fable model),
+ * in the foreground, so it ends inside the agent's turn and the after-turn
+ * check sees what it did, and in the agent's own worktree.
+ *
+ * @example
+ * checkHelperCall({ tool_input: { subagent_type: 'searcher', run_in_background: false } }) // { allow: true }
+ */
+export const checkHelperCall = ({
+    tool_input,
+}: {
+    tool_input: unknown
+}): ToolDecision => {
+    const input = HelperInputSchema.safeParse(tool_input)
+    if (!input.success) return deny('Agent got an input of the wrong shape.')
+    const { subagent_type, model, run_in_background, isolation } = input.data
+    if (model !== undefined && /fable/i.test(model)) {
+        return deny(`Fable models are refused: ${model}`)
+    }
+    if (subagent_type !== HELPER_TYPE) {
+        return deny(
+            `The only helper is "${HELPER_TYPE}": ${subagent_type ?? 'no subagent_type'} is not allowed.`
+        )
+    }
+    if (model !== undefined && model !== HELPER_MODEL) {
+        return deny(`Helpers always run on ${HELPER_MODEL}: ${model}`)
+    }
+    if (run_in_background !== false) {
+        return deny(
+            'Helpers run in the foreground: set run_in_background to false.'
+        )
+    }
+    if (isolation !== undefined) {
+        return deny('Helpers work in your own worktree: no isolation.')
+    }
+    return ALLOW
+}
+
+/**
+ * The guard's decision for a tool call a helper makes itself: only its
+ * read-only tools, whatever its agent may do.
+ */
+export const checkHelperTool = ({
+    tool_name,
+}: {
+    tool_name: string
+}): ToolDecision =>
+    HELPER_TOOLS.includes(tool_name)
+        ? ALLOW
+        : deny(
+              `A helper may only use ${HELPER_TOOLS.join(', ')}: not ${tool_name}.`
+          )

package/engine/guards/permission-rules.ts

@@ -0,0 +1,161 @@
+/**
+ * Pure: each role's SDK permission settings, the layer under the guard hook.
+ */
+import {
+    READ_TOOLS,
+    TOOLS,
+    type GuardArgs,
+    type GuardRole,
+} from './guard-roles'
+import { HELPER_TOOL, HELPER_TYPE } from './helper-rules'
+import {
+    checkCommands,
+    GIT_READ_SUBCOMMANDS,
+    PACKAGE_MANAGERS,
+    wordsOf,
+} from './shell-rules'
+import { LOCKFILES } from './write-rules'
+
+import {
+    featureMapPath,
+    isFeatureMapFolder,
+    type EngineConfig,
+} from '../config/engine-config'
+
+/** Built-in tools no agent gets, and secret files no agent reads. */
+export const BASE_DISALLOWED_TOOLS = [
+    'Workflow',
+    'Skill',
+    'WebFetch',
+    'WebSearch',
+    'Monitor',
+    'PowerShell',
+    'NotebookEdit',
+    'SendMessage',
+    'Artifact',
+    'RemoteTrigger',
+    'CronCreate',
+    'PushNotification',
+    'SendUserFile',
+    'EnterWorktree',
+    'ExitWorktree',
+    'ListMcpResourcesTool',
+    'ReadMcpResourceTool',
+    'Bash(run_in_background:true)',
+    'Read(~/.claude.json)',
+    'Read(~/.claude/**)',
+    'Read(~/.paseo/**)',
+    'Read(~/.ssh/**)',
+    'Read(~/.config/gh/**)',
+]
+
+/**
+ * Deny rules every role gets, so the package install and what it writes are
+ * shut at the SDK's permission layer too. `bunx` is left to the guard hook:
+ * a config's type check may run through it.
+ */
+export const INSTALL_DENY_RULES = [
+    ...['install', 'i', 'add', 'remove', 'update', 'pm'].flatMap((sub) => [
+        `Bash(bun ${sub})`,
+        `Bash(bun ${sub} *)`,
+    ]),
+    ...PACKAGE_MANAGERS.flatMap((name) => [`Bash(${name})`, `Bash(${name} *)`]),
+    'Edit(node_modules/**)',
+    'Edit(**/node_modules/**)',
+    ...LOCKFILES.flatMap((name) => [`Edit(${name})`, `Edit(**/${name})`]),
+]
+
+const readOnlyRules = (): string[] => [
+    'Bash(ls)',
+    'Bash(ls *)',
+    'Bash(cat *)',
+    'Bash(head *)',
+    'Bash(tail *)',
+    'Bash(wc *)',
+    'Bash(grep *)',
+    'Bash(rg *)',
+    'Bash(find *)',
+    'Bash(pwd)',
+    'Bash(sed -n *)',
+    ...GIT_READ_SUBCOMMANDS.flatMap((sub) => [
+        `Bash(git ${sub})`,
+        `Bash(git ${sub} *)`,
+    ]),
+]
+
+/**
+ * A role's SDK permission settings. Under `dontAsk` only pre-approved calls
+ * run, so `allowed` lists exactly what the role may do; `disallowed` shuts
+ * the rest; `tools` is the only built-in tools the agent sees. The guard hook
+ * (`checkToolCall`) still checks every call these let through.
+ */
+export const permissionRules = ({
+    role,
+    may_edit_tests,
+    config,
+}: GuardArgs & {
+    config: EngineConfig
+}): { tools: string[]; allowed: string[]; disallowed: string[] } => {
+    const commands = checkCommands({ role, config })
+    const shell = role === 'learner' ? [] : readOnlyRules()
+    // A bun test command takes extra args (a file, `-t`) only when it is one
+    // plain command; one with shell syntax runs as its exact copy.
+    const testRules = commands.tests.flatMap(({ run, results }) =>
+        results !== 'bun' || wordsOf(run) === null
+            ? [`Bash(${run})`]
+            : [`Bash(${run})`, `Bash(${run} *)`]
+    )
+    const checks = [
+        ...testRules,
+        ...commands.others.map((command) => `Bash(${command})`),
+    ]
+    const setup = config.test_setup_files.map((path) => `Edit(${path})`)
+    const tests = config.test_file_patterns.map((glob) => `Edit(${glob})`)
+    // The test helpers are the test-writer's too (#619).
+    const helpers = (config.test_helper_patterns ?? []).map(
+        (glob) => `Edit(${glob})`
+    )
+    // The feature map is the test-writer's too (#583): the file, or every
+    // page of a folder map (#597).
+    const map_path = featureMapPath({ config })
+    const map =
+        map_path === null
+            ? []
+            : isFeatureMapFolder({ path: map_path })
+              ? [`Edit(${map_path}/**/*.md)`]
+              : [`Edit(${map_path})`]
+    const writes: Record<
+        GuardRole,
+        { allowed: string[]; disallowed: string[] }
+    > = {
+        'test-writer': may_edit_tests
+            ? {
+                  allowed: [...tests, ...helpers, ...map, 'Bash(rm *)'],
+                  disallowed: setup,
+              }
+            : { allowed: [], disallowed: ['Edit', 'Write'] },
+        implementer: {
+            allowed: ['Edit(**)', 'Bash(rm *)'],
+            disallowed: may_edit_tests ? setup : [...tests, ...setup],
+        },
+        reviewer: { allowed: [], disallowed: ['Edit', 'Write'] },
+        learner: { allowed: [], disallowed: ['Edit', 'Write', 'Bash'] },
+    }
+    // Every role may start read-only `searcher` helpers (#627).
+    return {
+        tools: [...TOOLS[role], HELPER_TOOL],
+        allowed: [
+            ...READ_TOOLS,
+            `${HELPER_TOOL}(${HELPER_TYPE})`,
+            ...writes[role].allowed,
+            ...checks,
+            ...shell,
+            'mcp__luca',
+        ],
+        disallowed: [
+            ...BASE_DISALLOWED_TOOLS,
+            ...INSTALL_DENY_RULES,
+            ...writes[role].disallowed,
+        ],
+    }
+}

package/engine/guards/role-rules-helpers.ts

@@ -0,0 +1,48 @@
+import { checkToolCall, type GuardRole } from './role-rules'
+
+import type { EngineConfig } from '../config/engine-config'
+
+/** Seam 3: what the guard rule tests share: a config, a worktree, and `decide`. */
+
+export const CONFIG: EngineConfig = {
+    checks: {
+        test: 'bun test',
+        types: 'bunx --bun tsc --noEmit',
+        lint: 'bun run lint',
+    },
+    test_file_patterns: ['src/**/*.test.ts'],
+    test_setup_files: ['src/test-setup.ts'],
+    rule_files: [],
+}
+
+/** `CONFIG` with a feature map (#583). */
+export const WITH_MAP: EngineConfig = {
+    ...CONFIG,
+    feature_map: 'docs/feature-map.md',
+}
+
+export const WORKTREE = '/runs/run-1/tickets/11'
+
+/** `may_edit_tests` as the engine sets it on a normal (not refactor) ticket. */
+export const usual = (role: GuardRole): boolean => role === 'test-writer'
+
+export const decide = ({
+    role,
+    may_edit_tests,
+    tool_name,
+    tool_input,
+}: {
+    role: GuardRole
+    /** Defaults to `usual(role)`. */
+    may_edit_tests?: boolean
+    tool_name: string
+    tool_input: unknown
+}): boolean =>
+    checkToolCall({
+        role,
+        may_edit_tests: may_edit_tests ?? usual(role),
+        tool_name,
+        tool_input,
+        worktree: WORKTREE,
+        config: CONFIG,
+    }).allow