@meistrari/tela-skills 1.6.2 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/tela-skills",
-  "version": "1.6.2",
+  "version": "1.8.0",
   "description": "Tela API skills for Claude Code",
   "type": "module",
   "bin": {

package/skill/TELA_SKILL.md

@@ -91,6 +91,63 @@ bun --preload ~/.claude/skills/tela/preload.ts -e "console.log(await tela.listPr
 - `tela.waitForTestCase(testCaseId)` - Wait for test case to complete
 - `tela.abortTestCase(testCaseId)` - Abort a running test case
 
+### Agents (FCC)
+
+Create and iterate on Tela agents 100% via API — never clone the agent repository. An agent is a versioned git repo behind the API: every edit creates a commit (`commitHash` = agent version), `main` HEAD is the draft, and the published commit is what production runs.
+
+**Golden rule — instructions**: agent instructions live in the *Purpose* block inside `CLAUDE.md`. The rest of `CLAUDE.md` belongs to the agent template: it is not shown in the Tela UI and gets overwritten on template syncs. Always use `updateAgentPurpose` (writes to `putAgentFile('CLAUDE.md')` are refused). For extra reusable behavior, use skills (`createAgentCustomSkill`/`addAgentSkill`) and subagents — both survive template syncs.
+
+**Referencing things in the Purpose** (agents are NOT canvas — `{var}` syntax does not apply). Exact forms, written as plain text: text inputs as `<inputName>`, file inputs as `input/<inputName>/`, skills as `./.claude/skills/<name>/SKILL.md`, subagents as `./.claude/agents/<name>.md`, repo files by path. The Tela UI renders these as interactive chips — but only when they are plain text surrounded by spaces/punctuation and the target already exists (declare inputs / add skills first). **Never wrap references in backticks or code formatting** — the UI stops recognizing them. Never describe the output shape in the Purpose — that belongs in `output-format.json`.
+
+- `tela.listAgents(options?)` / `tela.getAgent(agentId)` - List/get agents (inputs synced with the repo)
+- `tela.createAgent({ title, projectId, description?, templateId? })` - Create an agent (provisions the repo)
+- `tela.updateAgent(agentId, payload)` / `tela.deleteAgent(agentId)` - Update metadata / soft delete
+- `tela.listAgentTemplates()` - Templates for `createAgent({ templateId })`
+- `tela.getAgentPurpose(agentId, options?)` / `tela.updateAgentPurpose(agentId, content, options?)` - Read/write the agent's instructions (the ONLY way to edit them)
+- `tela.getAgentFileTree(agentId, options?)` / `tela.getAgentFile(agentId, path, options?)` - Browse the repo (pass `branch`/`commitHash` for other versions)
+- `tela.putAgentFile(agentId, path, content, options?)` - Create/update a file (commits; refuses managed files — CLAUDE.md/AGENTS.md, `agent.config.json`, `output-format.json`, `.claude/settings.json` — which go through their dedicated functions)
+- `tela.deleteAgentFile` / `tela.renameAgentFile` - Remove/move files (protected runtime files are refused)
+- `tela.uploadAgentFiles(agentId, files, options?)` - Multipart upload for binaries/batches. Layout conventions: static supporting material goes in `references/`; never write into `input/` (creating `input/<x>/` implicitly declares variable `x`); `output/` is runtime-only. Execution `attachments` mount at `input/references/` in the sandbox
+- `tela.getAgentOutputSchema(agentId)` / `tela.updateAgentOutputSchema(agentId, schema)` - Read/write `output-format.json`. Flat map `attributeName -> { type, description, ... }` (no JSON Schema wrapper). Non-empty → structured JSON result; `{}` → markdown. These attribute paths are what test case attribute feedback and metrics reference
+- `tela.getAgentConfig(agentId)` / `tela.updateAgentConfig(agentId, partial)` - Read/merge `agent.config.json` (model/harness rejected — use the dedicated functions)
+- `tela.updateAgentModel(agentId, model)` / `tela.updateAgentHarness(agentId, harness)` - Change model/harness (server keeps template + layout in sync)
+- `tela.listAgentInputs` / `createAgentInput` / `updateAgentInput` / `deleteAgentInput` - Declared input variables. Name: `^[a-zA-Z0-9_-]+$` (`references` is reserved). Declaring commits `input/<name>/.gitkeep` to the repo — the folder is the declaration. Executions are validated against declarations (unknown name, type mismatch, or missing required input → 400)
+- `tela.discoverAgentSkill(ref)` / `tela.addAgentSkill(agentId, ref)` / `tela.listAgentSkillsStore()` - Skills from GitHub (`gh:owner/repo/path[@branch]`)
+- `tela.createAgentCustomSkill(agentId, name, skillMd)` - Author a skill directly in the repo
+- `tela.createAgentSubagent(agentId, name)` / `tela.updateAgentSubagent(agentId, name, content)` - Subagents (`.claude/agents/<name>.md`)
+- `tela.addAgentCapability(agentId, { kind, sourceId })` - Attach a published canvas/workflow/agent as a tool
+- `tela.restoreAgentVersion(agentId, commitHash)` / `tela.publishAgent(agentId, commitHash)` - Rollback / publish
+- `tela.testAgent(agentId, payload)` / `tela.runAgent(agentId, payload)` - Execute draft (`main`) / production (published). Async: 202 + `sessionId`
+- `tela.waitForAgentSession(sessionId)` / `tela.runAgentAndWait(agentId, payload, options?)` - Poll to completion / execute+wait in one call
+- `tela.getAgentSessionThread` / `getAgentSessionTimeline` / `getAgentSessionFiles` / `getAgentSessionFile` - Inspect a session
+- `tela.cancelAgentSession` / `tela.endAgentSession` - Stop sessions
+- `tela.buildAgentExecutionInputs(variables, options?)` - Payload helper (vault:// values become file inputs)
+- `tela.getAgentUrl(agentId)` - Link to the agent in the Tela app
+
+### Agent Test Cases
+
+Test cases for agents (FCC). Runs are keyed by `(testCaseId, commitHash)` — one run per test case per agent version. Run/continue/run-all return `202 { executionId }` immediately; poll with `waitForAgentTestCaseRun`. Derived statuses: `new`, `running`, `executed`, `success`, `failed`, `error` (terminal: `success`/`failed`/`error`).
+
+- `tela.listAgentTestCases(agentId, options?)` - List test cases (pass `commitHash` to attach runs/stats)
+- `tela.createAgentTestCase(agentId, payload)` - Create a test case
+- `tela.updateAgentTestCase(agentId, testId, payload)` - Update a test case
+- `tela.deleteAgentTestCase(agentId, testId)` - Delete a test case
+- `tela.runAgentTestCase(agentId, testId, commitHash)` - Run against an agent version
+- `tela.continueAgentTestCase(agentId, testId, commitHash, message)` - Continue session (multiturn)
+- `tela.runAllAgentTestCases(agentId, { commitHash, testCaseIds? | filters? })` - Batch run (returns `skipped` reasons)
+- `tela.getAgentTestCaseRun(agentId, testId, commitHash)` - Get the run for a commit
+- `tela.listAgentTestCaseRuns(agentId, testId, options?)` - Run history across commits (cursor pagination)
+- `tela.waitForAgentTestCaseRun(agentId, testId, commitHash, options?)` - Poll until terminal status
+- `tela.updateAgentTestCaseAttributeFeedback(agentId, testId, commitHash, attributes)` - Thumbs per attribute (feeds the answer bank)
+- `tela.getAgentTestCaseStats(agentId, commitHash, options?)` - Aggregated stats for a commit
+- `tela.listAgentTestMetrics(agentId)` / `createAgentTestMetric` / `updateAgentTestMetric` / `deleteAgentTestMetric` - Custom metrics over output attributes
+- `tela.listAgentTestCaseTags(agentId)` / `createAgentTestCaseTag` / `updateAgentTestCaseTag` / `deleteAgentTestCaseTag` - Tag CRUD
+- `tela.getAgentTestCaseTags(agentId, testId)` / `addAgentTestCaseTags` / `removeAgentTestCaseTag` - Tag assignment
+- `tela.bulkAddAgentTestCaseTags(agentId, testCaseIds, tagIds)` / `bulkRemoveAgentTestCaseTags(...)` - Bulk tagging
+- `tela.getAgentHistory(agentId, options?)` / `tela.getLatestAgentCommit(agentId)` - Resolve agent versions (commitHash)
+- `tela.buildAgentTestInputs(variables, options?)` / `tela.createAgentTestCasePayload(variables, options?)` - Payload helpers (vault:// values become file inputs)
+- `tela.getAgentTestCaseRunStatus(run)` - Derive run status locally
+
 ### Tasks
 
 - `tela.listTasks(options?)` - List tasks with pagination and filtering
@@ -192,6 +249,66 @@ console.log('Variables:', version?.variables?.map(v => v.name))
 "
 ```
 
+### Create an Agent and Iterate via API (no repo cloning)
+```bash
+bun --preload ~/.claude/skills/tela/preload.ts -e "
+const agent = await tela.createAgent({ title: 'Contract Analyzer', projectId: 'PROJECT_ID' })
+
+await tela.updateAgentPurpose(agent.id, [
+  'You analyze contracts and extract the parties and total amount.',
+  'The contract PDF is at input/contract/.',
+  'Always answer in Brazilian Portuguese.',
+].join('\n'))
+
+await tela.createAgentInput(agent.id, { name: 'contract', type: 'file', required: true })
+await tela.updateAgentOutputSchema(agent.id, {
+  parties: { type: 'array', items: { type: 'string' }, description: 'All contract parties' },
+  total: { type: 'number', description: 'Total amount' },
+})
+
+const { status, output } = await tela.runAgentAndWait(agent.id, {
+  message: 'Analyze the attached contract',
+  inputSchema: tela.buildAgentExecutionInputs({ contract: await tela.uploadFile('./contract.pdf') }),
+})
+console.log(status, output)
+console.log('Edit in UI:', tela.getAgentUrl(agent.id))
+"
+```
+
+### Publish an Agent Version
+```bash
+bun --preload ~/.claude/skills/tela/preload.ts -e "
+const commitHash = await tela.getLatestAgentCommit('AGENT_ID')
+await tela.publishAgent('AGENT_ID', commitHash)
+console.log('Published', commitHash)
+"
+```
+
+### Create and Run an Agent Test Case
+```bash
+bun --preload ~/.claude/skills/tela/preload.ts -e "
+const agentId = 'AGENT_ID'
+const vaultRef = await tela.uploadFile('./contract.pdf')
+
+const testCase = await tela.createAgentTestCase(agentId, tela.createAgentTestCasePayload({
+  document: vaultRef,
+  instructions: 'Extract the parties and total amount',
+}, {
+  title: 'Contract extraction',
+  evaluationInstructions: 'The output must list both parties and the correct total.',
+  fileNames: { document: 'contract.pdf' },
+}))
+
+const commitHash = await tela.getLatestAgentCommit(agentId)
+await tela.runAgentTestCase(agentId, testCase.id, commitHash)
+
+const { run, status } = await tela.waitForAgentTestCaseRun(agentId, testCase.id, commitHash)
+console.log('Status:', status)
+console.log('Output:', run.output)
+console.log('Validation:', run.validationSummary)
+"
+```
+
 ### List Tasks
 ```bash
 bun --preload ~/.claude/skills/tela/preload.ts -e "
@@ -332,7 +449,9 @@ bun localhost.ts "console.log(await tela.listProjects())"
 ├── prompts.ts            # Prompt/Canvas list functions
 ├── canvas.ts             # Canvas create/update functions
 ├── workflows.ts          # Workflow create/update/run/validation functions
-├── test-cases.ts         # Test case functions
+├── test-cases.ts         # Test case functions (prompt/canvas)
+├── agents.ts             # Agent editing/execution functions (FCC)
+├── agent-test-cases.ts   # Agent test case functions (FCC)
 ├── tasks.ts              # Task management functions
 ├── vault.ts              # Vault file management functions
 └── localhost-utils.ts    # Docker discovery, JWT signing, workspace fetching (internal, not on tela global)

package/skill/agent-test-cases.test.ts

@@ -0,0 +1,316 @@
+import { beforeEach, describe, expect, mock, test } from 'bun:test'
+
+const apiRequest = mock(async (_endpoint: string, _options?: RequestInit): Promise<unknown> => ({ data: {} }))
+
+class ApiRequestError extends Error {
+    constructor(public readonly status: number, message: string) {
+        super(message)
+        this.name = 'ApiRequestError'
+    }
+}
+
+void mock.module('./common.ts', () => ({
+    apiRequest,
+    ApiRequestError,
+}))
+
+describe('agent-test-cases', () => {
+    beforeEach(() => {
+        apiRequest.mockClear()
+        apiRequest.mockImplementation(async () => ({ data: {} }))
+    })
+
+    test('lists test cases with repeated array query params', async () => {
+        const { listAgentTestCases } = await import('./agent-test-cases.ts')
+        apiRequest.mockImplementation(async () => ({ data: [] }))
+
+        await listAgentTestCases('agent-1', {
+            commitHash: 'abc123',
+            title: 'search',
+            status: ['failed', 'error'],
+            tagIds: ['t1', 't2'],
+            createdBy: ['u1'],
+            createdAtSince: '2026-01-01T00:00:00Z',
+        })
+
+        const [endpoint] = apiRequest.mock.calls[0]!
+        const query = new URLSearchParams(String(endpoint).split('?')[1])
+
+        expect(String(endpoint).startsWith('/agent/agent-1/tests?')).toBe(true)
+        expect(query.get('commitHash')).toBe('abc123')
+        expect(query.get('title')).toBe('search')
+        expect(query.getAll('status')).toEqual(['failed', 'error'])
+        expect(query.getAll('tagIds')).toEqual(['t1', 't2'])
+        expect(query.getAll('createdBy')).toEqual(['u1'])
+        expect(query.get('createdAtSince')).toBe('2026-01-01T00:00:00Z')
+    })
+
+    test('omits the query string when no options are given', async () => {
+        const { listAgentTestCases } = await import('./agent-test-cases.ts')
+        apiRequest.mockImplementation(async () => ({ data: [] }))
+
+        await listAgentTestCases('agent-1')
+
+        expect(apiRequest.mock.calls[0]![0]).toBe('/agent/agent-1/tests')
+    })
+
+    test('pre-serializes bodies so vault refs are not rewritten by parsePayload', async () => {
+        const { createAgentTestCase } = await import('./agent-test-cases.ts')
+
+        await createAgentTestCase('agent-1', {
+            inputs: [{ type: 'file', name: 'doc', vaultRef: 'vault://abc', filename: 'doc.pdf' }],
+        })
+
+        const [endpoint, options] = apiRequest.mock.calls[0]!
+        expect(endpoint).toBe('/agent/agent-1/tests')
+        expect(options?.method).toBe('POST')
+        expect(typeof options?.body).toBe('string')
+
+        const body = JSON.parse(String(options?.body))
+        expect(body.inputs[0].vaultRef).toBe('vault://abc')
+    })
+
+    test('unwraps the { data } envelope', async () => {
+        const { createAgentTestCase } = await import('./agent-test-cases.ts')
+        apiRequest.mockImplementation(async () => ({ data: { id: 'tc-1', title: 'Test' } }))
+
+        const testCase = await createAgentTestCase('agent-1', { title: 'Test' })
+
+        expect(testCase).toEqual({ id: 'tc-1', title: 'Test' } as any)
+    })
+
+    test('runs a test case against a commit', async () => {
+        const { runAgentTestCase } = await import('./agent-test-cases.ts')
+        apiRequest.mockImplementation(async () => ({ data: { executionId: 'exec-1' } }))
+
+        const result = await runAgentTestCase('agent-1', 'tc-1', 'abc123')
+
+        const [endpoint, options] = apiRequest.mock.calls[0]!
+        expect(endpoint).toBe('/agent/agent-1/tests/tc-1/run')
+        expect(JSON.parse(String(options?.body))).toEqual({ commitHash: 'abc123' })
+        expect(result.executionId).toBe('exec-1')
+    })
+
+    test('continues a session with a message', async () => {
+        const { continueAgentTestCase } = await import('./agent-test-cases.ts')
+        apiRequest.mockImplementation(async () => ({ data: { executionId: 'exec-2' } }))
+
+        await continueAgentTestCase('agent-1', 'tc-1', 'abc123', 'next turn')
+
+        const [endpoint, options] = apiRequest.mock.calls[0]!
+        expect(endpoint).toBe('/agent/agent-1/tests/tc-1/continue')
+        expect(JSON.parse(String(options?.body))).toEqual({ commitHash: 'abc123', message: 'next turn' })
+    })
+
+    test('sends attribute feedback wrapped in attributes', async () => {
+        const { updateAgentTestCaseAttributeFeedback } = await import('./agent-test-cases.ts')
+
+        await updateAgentTestCaseAttributeFeedback('agent-1', 'tc-1', 'abc123', [
+            { path: 'summary', feedback: 1 },
+            { path: 'total', feedback: 0, message: 'wrong' },
+        ])
+
+        const [endpoint, options] = apiRequest.mock.calls[0]!
+        expect(endpoint).toBe('/agent/agent-1/tests/tc-1/runs/abc123/attribute-feedback')
+        expect(options?.method).toBe('PATCH')
+
+        const body = JSON.parse(String(options?.body))
+        expect(body.attributes).toHaveLength(2)
+        expect(body.attributes[1]).toEqual({ path: 'total', feedback: 0, message: 'wrong' })
+    })
+
+    test('requires commitHash on the stats endpoint query', async () => {
+        const { getAgentTestCaseStats } = await import('./agent-test-cases.ts')
+
+        await getAgentTestCaseStats('agent-1', 'abc123', { tagIds: ['t1'] })
+
+        const [endpoint] = apiRequest.mock.calls[0]!
+        const query = new URLSearchParams(String(endpoint).split('?')[1])
+
+        expect(String(endpoint).startsWith('/agent/agent-1/tests/stats?')).toBe(true)
+        expect(query.get('commitHash')).toBe('abc123')
+        expect(query.getAll('tagIds')).toEqual(['t1'])
+    })
+
+    test('run history keeps pagination fields from the response envelope', async () => {
+        const { listAgentTestCaseRuns } = await import('./agent-test-cases.ts')
+        // This endpoint's envelope is { data: entries, nextCursor, totalRuns } —
+        // pagination fields live beside data, not inside it
+        apiRequest.mockImplementation(async () => ({
+            data: [{ commitHash: 'abc123', score: 1 }],
+            nextCursor: 'cursor-1',
+            totalRuns: 5,
+        }))
+
+        const result = await listAgentTestCaseRuns('agent-1', 'tc-1', { limit: 1 })
+
+        expect(apiRequest.mock.calls[0]![0]).toBe('/agent/agent-1/tests/tc-1/runs?limit=1')
+        expect(result.data).toHaveLength(1)
+        expect(result.nextCursor).toBe('cursor-1')
+        expect(result.totalRuns).toBe(5)
+    })
+
+    describe('buildAgentTestInputs', () => {
+        test('splits text and vault file values', async () => {
+            const { buildAgentTestInputs } = await import('./agent-test-cases.ts')
+
+            const inputs = buildAgentTestInputs({
+                context: 'Some text',
+                document: 'vault://abc123',
+            }, { fileNames: { document: 'report.pdf' } })
+
+            expect(inputs).toEqual([
+                { type: 'text', name: 'context', content: 'Some text' },
+                { type: 'file', name: 'document', vaultRef: 'vault://abc123', filename: 'report.pdf' },
+            ])
+        })
+
+        test('defaults the filename to the input name', async () => {
+            const { buildAgentTestInputs } = await import('./agent-test-cases.ts')
+
+            const inputs = buildAgentTestInputs({ document: 'vault://abc123' })
+
+            expect(inputs[0]).toEqual({ type: 'file', name: 'document', vaultRef: 'vault://abc123', filename: 'document' })
+        })
+    })
+
+    describe('createAgentTestCasePayload', () => {
+        test('builds payload with expectations and derived title', async () => {
+            const { createAgentTestCasePayload } = await import('./agent-test-cases.ts')
+
+            const payload = createAgentTestCasePayload({ input: 'Hello world, this is a long input value' }, {
+                evaluationInstructions: 'Must greet back',
+            })
+
+            expect(payload.title).toBe(`Test: ${'Hello world, this is a long input value'.slice(0, 30)}...`)
+            expect(payload.evaluationInstructions).toBe('Must greet back')
+            expect(payload.inputs).toHaveLength(1)
+        })
+
+        test('falls back to the first filename for file-only cases', async () => {
+            const { createAgentTestCasePayload } = await import('./agent-test-cases.ts')
+
+            const payload = createAgentTestCasePayload({ doc: 'vault://abc' }, { fileNames: { doc: 'contract.pdf' } })
+
+            expect(payload.title).toBe('Test: contract.pdf')
+        })
+    })
+
+    describe('getAgentTestCaseRunStatus', () => {
+        const baseRun = {
+            executionSessionId: null as string | null,
+            executionStatus: null as any,
+            evaluationSessionId: null as string | null,
+            evaluationStatus: null as any,
+            feedback: null as 0 | 1 | null,
+        }
+
+        test('derives every status branch', async () => {
+            const { getAgentTestCaseRunStatus } = await import('./agent-test-cases.ts')
+
+            expect(getAgentTestCaseRunStatus(null)).toBe('new')
+            expect(getAgentTestCaseRunStatus({ ...baseRun, executionStatus: 'error' })).toBe('error')
+            expect(getAgentTestCaseRunStatus({ ...baseRun, executionStatus: 'completed', evaluationStatus: 'error' })).toBe('error')
+            expect(getAgentTestCaseRunStatus({ ...baseRun, executionStatus: 'running' })).toBe('running')
+            expect(getAgentTestCaseRunStatus({ ...baseRun, executionStatus: 'completed', evaluationSessionId: 's', evaluationStatus: 'running' })).toBe('running')
+            expect(getAgentTestCaseRunStatus({ ...baseRun, executionStatus: 'completed' })).toBe('executed')
+            expect(getAgentTestCaseRunStatus({ ...baseRun, executionStatus: 'completed', evaluationSessionId: 's', evaluationStatus: 'completed', feedback: 1 })).toBe('success')
+            expect(getAgentTestCaseRunStatus({ ...baseRun, executionStatus: 'completed', evaluationSessionId: 's', evaluationStatus: 'completed', feedback: 0 })).toBe('failed')
+            expect(getAgentTestCaseRunStatus({ ...baseRun, executionStatus: 'completed', evaluationSessionId: 's', evaluationStatus: 'failed' })).toBe('failed')
+            expect(getAgentTestCaseRunStatus({ ...baseRun, executionSessionId: 's' })).toBe('executed')
+        })
+    })
+
+    describe('waitForAgentTestCaseRun', () => {
+        test('retries 404s until the run appears, then resolves on terminal status', async () => {
+            const { waitForAgentTestCaseRun } = await import('./agent-test-cases.ts')
+
+            let calls = 0
+            apiRequest.mockImplementation(async () => {
+                calls++
+                if (calls === 1)
+                    throw new ApiRequestError(404, 'API request failed: 404 Not Found - {}')
+                if (calls === 2) {
+                    return { data: { executionStatus: 'running', executionSessionId: 's', evaluationSessionId: null, evaluationStatus: null, feedback: null } }
+                }
+                return { data: { executionStatus: 'completed', executionSessionId: 's', evaluationSessionId: 'e', evaluationStatus: 'completed', feedback: 1 } }
+            })
+
+            const { status } = await waitForAgentTestCaseRun('agent-1', 'tc-1', 'abc123', { intervalMs: 1 })
+
+            expect(status).toBe('success')
+            expect(calls).toBe(3)
+        })
+
+        test('stops at executed when until is executed', async () => {
+            const { waitForAgentTestCaseRun } = await import('./agent-test-cases.ts')
+
+            apiRequest.mockImplementation(async () => ({
+                data: { executionStatus: 'completed', executionSessionId: 's', evaluationSessionId: null, evaluationStatus: null, feedback: null },
+            }))
+
+            const { status } = await waitForAgentTestCaseRun('agent-1', 'tc-1', 'abc123', { intervalMs: 1, until: 'executed' })
+
+            expect(status).toBe('executed')
+        })
+
+        test('throws after maxAttempts without a terminal status', async () => {
+            const { waitForAgentTestCaseRun } = await import('./agent-test-cases.ts')
+
+            apiRequest.mockImplementation(async () => ({
+                data: { executionStatus: 'running', executionSessionId: 's', evaluationSessionId: null, evaluationStatus: null, feedback: null },
+            }))
+
+            expect(waitForAgentTestCaseRun('agent-1', 'tc-1', 'abc123', { intervalMs: 1, maxAttempts: 2 }))
+                .rejects
+                .toThrow('did not complete within timeout')
+        })
+
+        test('rethrows non-404 API errors', async () => {
+            const { waitForAgentTestCaseRun } = await import('./agent-test-cases.ts')
+
+            apiRequest.mockImplementation(async () => {
+                throw new ApiRequestError(500, 'API request failed: 500 Internal Server Error - {}')
+            })
+
+            expect(waitForAgentTestCaseRun('agent-1', 'tc-1', 'abc123', { intervalMs: 1 }))
+                .rejects
+                .toThrow('500')
+        })
+
+        test('rethrows untyped errors even when the message mentions 404', async () => {
+            const { waitForAgentTestCaseRun } = await import('./agent-test-cases.ts')
+
+            apiRequest.mockImplementation(async () => {
+                throw new Error('fetch failed with 404 somewhere')
+            })
+
+            expect(waitForAgentTestCaseRun('agent-1', 'tc-1', 'abc123', { intervalMs: 1 }))
+                .rejects
+                .toThrow('fetch failed')
+        })
+    })
+
+    describe('getLatestAgentCommit', () => {
+        test('returns the newest commit hash', async () => {
+            const { getLatestAgentCommit } = await import('./agent-test-cases.ts')
+            apiRequest.mockImplementation(async () => ({
+                data: { commits: [{ commitHash: 'abc123' }], branch: 'main', pagination: { page: 1, limit: 1, totalCount: 5, hasMore: true } },
+            }))
+
+            const hash = await getLatestAgentCommit('agent-1')
+
+            expect(apiRequest.mock.calls[0]![0]).toBe('/agent/agent-1/history?limit=1')
+            expect(hash).toBe('abc123')
+        })
+
+        test('throws when the agent has no commits', async () => {
+            const { getLatestAgentCommit } = await import('./agent-test-cases.ts')
+            apiRequest.mockImplementation(async () => ({
+                data: { commits: [], branch: 'main', pagination: { page: 1, limit: 1, totalCount: 0, hasMore: false } },
+            }))
+
+            expect(getLatestAgentCommit('agent-1')).rejects.toThrow('has no commits')
+        })
+    })
+})