x
', token: 't', uploadUrl: 'https://example.test/upload', hash: 'my-id', }) const calledUrl = (fetchMock as unknown as { mock: { calls: [string | URL | Request][] } }).mock.calls[0][0] expect(calledUrl.toString()).toContain('hash=my-id') }) test('passes ttl=30 query param when provided', async () => { const fetchMock = mockFetch({ id: 'x', url: 'https://x', expiresAt: '2026-07-20T00:00:00.000Z' }) globalThis.fetch = fetchMock await uploadArtifact({ html: 'x
', token: 't', uploadUrl: 'https://example.test/upload', ttl: 30, }) const calledUrl = (fetchMock as unknown as { mock: { calls: [string | URL | Request][] } }).mock.calls[0][0] expect(calledUrl.toString()).toContain('ttl=30') }) test('throws with error code when body contains {error} (Deno Deploy flattens status)', async () => { globalThis.fetch = mockFetch({ error: 'payload_too_large' }, 200) await expect( uploadArtifact({ html: 'x'.repeat(100), token: 't', uploadUrl: 'https://example.test/upload', }), ).rejects.toThrow(/payload_too_large/) }) test('throws on non-JSON body', async () => { globalThis.fetch = mock((_u: string | URL | Request) => Promise.resolve(new Response('Internal Server Error', { status: 500 })), ) as unknown as typeof fetch await expect( uploadArtifact({ html: '', token: 't', uploadUrl: 'https://example.test/upload' }), ).rejects.toThrow() }) }) ``` - [ ] **Step 2: Run test to verify it fails** ```bash bun test packages/builtin-tools/src/tools/ArtifactTool/__tests__/client.test.ts ``` Expected: FAIL with `Cannot find module '../client.js'` or similar. - [ ] **Step 3: Implement the client** ```typescript // packages/builtin-tools/src/tools/ArtifactTool/client.ts export type UploadResult = { id: string url: string expiresAt: string } export type UploadParams = { html: string token: string uploadUrl: string hash?: string ttl?: 7 | 30 } export async function uploadArtifact(params: UploadParams): Promise" }`. Always parse body first.
const text = await response.text()
let parsed: unknown
try {
parsed = JSON.parse(text)
} catch {
throw new Error(`Artifact upload failed: HTTP ${response.status} (non-JSON body)`)
}
if (parsed && typeof parsed === 'object' && 'error' in parsed) {
const code = (parsed as { error: unknown }).error
throw new Error(`Artifact upload failed: ${String(code)}`)
}
const data = parsed as Partial
if (typeof data.id !== 'string' || typeof data.url !== 'string' || typeof data.expiresAt !== 'string') {
throw new Error(`Artifact upload returned malformed body: ${text.slice(0, 200)}`)
}
return { id: data.id, url: data.url, expiresAt: data.expiresAt }
}
```
- [ ] **Step 4: Run tests to verify they pass**
```bash
bun test packages/builtin-tools/src/tools/ArtifactTool/__tests__/client.test.ts
```
Expected: PASS (5 tests).
- [ ] **Step 5: Commit**
```bash
git add packages/builtin-tools/src/tools/ArtifactTool/client.ts packages/builtin-tools/src/tools/ArtifactTool/__tests__/client.test.ts
git commit -m "feat(artifact): add HTTP client with body-error parsing"
```
---
## Task 3: ArtifactTool prompt (name + description)
**Files:**
- Create: `packages/builtin-tools/src/tools/ArtifactTool/prompt.ts`
- [ ] **Step 1: Write prompt file**
```typescript
// packages/builtin-tools/src/tools/ArtifactTool/prompt.ts
export const ARTIFACT_TOOL_NAME = 'artifact'
export async function describeArtifactTool(): Promise {
return 'Upload an HTML file to the cloud-artifacts hosting service and get back a public URL. Pass `hash` to overwrite a previously-uploaded artifact (keeps URL stable).'
}
export async function getArtifactToolPrompt(): Promise {
return `Upload an HTML file to a public hosting service and return a shareable URL plus an internal \`id\` (the "hash").
## Inputs
- \`file_path\` (required): absolute path to a local HTML file.
- \`hash\` (optional): if provided, overwrites the artifact with the same hash (URL stays the same). If omitted, a new random id is generated.
- \`ttl\` (optional, default \`7\`): artifact lifetime in days. Must be \`7\` or \`30\`.
## Output
\`{ id, url, expiresAt }\` — \`id\` is the hash (save it for future overwrite calls), \`url\` is publicly accessible.
## Workflow
1. Use the Write tool to create a local HTML file.
2. Call this tool with its \`file_path\`.
3. If iterating on the same artifact, pass back the \`id\` returned from the first call as \`hash\` so the URL stays stable.
## Errors
The tool surfaces backend error codes verbatim (e.g. \`payload_too_large\`, \`unauthorized\`). If the file does not exist or is not a regular file, the tool returns an \`error\` field without making an HTTP request.`
}
```
- [ ] **Step 2: Commit**
```bash
git add packages/builtin-tools/src/tools/ArtifactTool/prompt.ts
git commit -m "feat(artifact): add tool name, description, and prompt"
```
---
## Task 4: ArtifactTool definition (schema + call + render + map)
**Files:**
- Create: `packages/builtin-tools/src/tools/ArtifactTool/ArtifactTool.ts`
- [ ] **Step 1: Write the tool definition**
```typescript
// packages/builtin-tools/src/tools/ArtifactTool/ArtifactTool.ts
import { stat, readFile } from 'fs/promises'
import { z } from 'zod/v4'
import type { ToolResultBlockParam } from 'src/Tool.js'
import { buildTool } from 'src/Tool.js'
import { lazySchema } from 'src/utils/lazySchema.js'
import { ARTIFACT_TOOL_NAME, describeArtifactTool, getArtifactToolPrompt } from './prompt.js'
import { getArtifactsToken, getUploadUrl } from './config.js'
import { uploadArtifact } from './client.js'
const inputSchema = lazySchema(() =>
z.strictObject({
file_path: z.string().describe('Absolute path to a local HTML file to upload.'),
hash: z
.string()
.regex(/^[A-Za-z0-9_-]{1,128}$/, 'must match ^[A-Za-z0-9_-]{1,128}$')
.optional()
.describe('If provided, overwrites the existing artifact with this hash (URL stays stable). If omitted, a new random id is generated.'),
ttl: z.union([z.literal(7), z.literal(30)]).default(7).describe('Lifetime in days. Must be 7 or 30. Default 7.'),
}),
)
type InputSchema = ReturnType
type ArtifactInput = z.infer
const outputSchema = lazySchema(() =>
z.object({
id: z.string(),
url: z.string(),
expiresAt: z.string(),
}),
)
type OutputSchema = ReturnType
type ArtifactOutput = z.infer
type ArtifactErrorOutput = ArtifactOutput & { error?: string }
export const ArtifactTool = buildTool({
name: ARTIFACT_TOOL_NAME,
searchHint: 'upload html artifact share url cloud publish progress report public link',
maxResultSizeChars: 2_000,
shouldDefer: true,
strict: true,
get inputSchema(): InputSchema {
return inputSchema()
},
get outputSchema(): OutputSchema {
return outputSchema()
},
async description() {
return describeArtifactTool()
},
async prompt() {
return getArtifactToolPrompt()
},
isEnabled() {
return true
},
isConcurrencySafe() {
return false
},
isReadOnly() {
return false
},
requiresUserInteraction() {
return true
},
userFacingName() {
return 'Artifact'
},
renderToolUseMessage(input: Partial) {
const hashPart = input.hash ? ` (hash=${input.hash})` : ''
return `Upload artifact: ${input.file_path ?? '...'}${hashPart}`
},
mapToolResultToToolResultBlockParam(content: ArtifactErrorOutput, toolUseID: string): ToolResultBlockParam {
if (content.error) {
return {
tool_use_id: toolUseID,
type: 'tool_result',
is_error: true,
content: content.error,
}
}
return {
tool_use_id: toolUseID,
type: 'tool_result',
content: `Artifact uploaded: ${content.url} (id: ${content.id}, expires: ${content.expiresAt})`,
}
},
async call(input: ArtifactInput) {
const { file_path, hash, ttl } = input
let size: number
try {
const fileStat = await stat(file_path)
if (!fileStat.isFile()) {
return { data: { id: '', url: '', expiresAt: '', error: `Path is not a regular file: ${file_path}` } }
}
size = fileStat.size
} catch {
return { data: { id: '', url: '', expiresAt: '', error: `File does not exist or is not readable: ${file_path}` } }
}
if (size > 10 * 1024 * 1024) {
return { data: { id: '', url: '', expiresAt: '', error: `File is ${size} bytes; backend limit is 10MB.` } }
}
let html: string
try {
html = await readFile(file_path, 'utf8')
} catch {
return { data: { id: '', url: '', expiresAt: '', error: `Failed to read file: ${file_path}` } }
}
try {
const result = await uploadArtifact({
html,
token: getArtifactsToken(),
uploadUrl: getUploadUrl(),
hash,
ttl,
})
return { data: result }
} catch (e) {
const message = e instanceof Error ? e.message : String(e)
return { data: { id: '', url: '', expiresAt: '', error: message } }
}
},
})
```
- [ ] **Step 2: Commit**
```bash
git add packages/builtin-tools/src/tools/ArtifactTool/ArtifactTool.ts
git commit -m "feat(artifact): add buildTool definition with file validation"
```
---
## Task 5: Tool end-to-end tests
**Files:**
- Test: `packages/builtin-tools/src/tools/ArtifactTool/__tests__/ArtifactTool.test.ts`
- [ ] **Step 1: Write the e2e tool test**
```typescript
// packages/builtin-tools/src/tools/ArtifactTool/__tests__/ArtifactTool.test.ts
import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs'
import { tmpdir } from 'os'
import { join } from 'path'
import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test'
import { ArtifactTool } from '../ArtifactTool.js'
const TEST_DIR = join(tmpdir(), 'artifact-tool-test')
const TEST_FILE = join(TEST_DIR, 'report.html')
const MISSING_FILE = join(TEST_DIR, 'does-not-exist.html')
const DIR_AS_FILE = TEST_DIR
const originalFetch = globalThis.fetch
function mockFetchSuccess(body: object): typeof fetch {
return mock(() =>
Promise.resolve(
new Response(JSON.stringify(body), {
status: 200,
headers: { 'Content-Type': 'application/json' },
}),
),
) as unknown as typeof fetch
}
describe('ArtifactTool.call', () => {
beforeEach(() => {
mkdirSync(TEST_DIR, { recursive: true })
writeFileSync(TEST_FILE, 'test report
', 'utf8')
process.env.CLAUDE_ARTIFACTS_TOKEN = 'test-token'
process.env.CLAUDE_ARTIFACTS_URL = 'https://example.test'
})
afterEach(() => {
if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true, force: true })
delete process.env.CLAUDE_ARTIFACTS_TOKEN
delete process.env.CLAUDE_ARTIFACTS_URL
globalThis.fetch = originalFetch
})
test('uploads existing HTML file and returns id/url/expiresAt', async () => {
globalThis.fetch = mockFetchSuccess({
id: 'abc123',
url: 'https://example.test/7d/abc123.html',
expiresAt: '2026-06-27T10:00:00.000Z',
})
const result = await ArtifactTool.call({ file_path: TEST_FILE, ttl: 7 }, {} as never, {} as never, {} as never)
expect(result.data).toMatchObject({
id: 'abc123',
url: 'https://example.test/7d/abc123.html',
expiresAt: '2026-06-27T10:00:00.000Z',
})
expect((result.data as { error?: string }).error).toBeUndefined()
})
test('passes hash through when overwriting', async () => {
const fetchMock = mockFetchSuccess({
id: 'stable-id',
url: 'https://example.test/7d/stable-id.html',
expiresAt: '2026-06-27T10:00:00.000Z',
})
globalThis.fetch = fetchMock
await ArtifactTool.call({ file_path: TEST_FILE, hash: 'stable-id', ttl: 7 }, {} as never, {} as never, {} as never)
const calledUrl = (fetchMock as unknown as { mock: { calls: [string | URL | Request][] } }).mock.calls[0][0]
expect(calledUrl.toString()).toContain('hash=stable-id')
})
test('returns error when file does not exist (no HTTP call)', async () => {
let fetchCalled = false
globalThis.fetch = mock(() => {
fetchCalled = true
return Promise.resolve(new Response('{}'))
}) as unknown as typeof fetch
const result = await ArtifactTool.call({ file_path: MISSING_FILE, ttl: 7 }, {} as never, {} as never, {} as never)
expect(fetchCalled).toBe(false)
expect((result.data as { error?: string }).error).toContain('does not exist')
})
test('returns error when path is a directory', async () => {
const result = await ArtifactTool.call({ file_path: DIR_AS_FILE, ttl: 7 }, {} as never, {} as never, {} as never)
expect((result.data as { error?: string }).error).toContain('not a regular file')
})
test('returns error verbatim when backend rejects', async () => {
globalThis.fetch = mock(() =>
Promise.resolve(new Response(JSON.stringify({ error: 'payload_too_large' }), { status: 200 })),
) as unknown as typeof fetch
// Force the size guard to pass by writing a small file but having backend complain.
const result = await ArtifactTool.call({ file_path: TEST_FILE, ttl: 7 }, {} as never, {} as never, {} as never)
expect((result.data as { error?: string }).error).toContain('payload_too_large')
})
})
```
- [ ] **Step 2: Run the e2e test**
```bash
bun test packages/builtin-tools/src/tools/ArtifactTool/__tests__/ArtifactTool.test.ts
```
Expected: PASS (5 tests).
- [ ] **Step 3: Commit**
```bash
git add packages/builtin-tools/src/tools/ArtifactTool/__tests__/ArtifactTool.test.ts
git commit -m "test(artifact): add end-to-end tool tests for upload/error paths"
```
---
## Task 6: Export ArtifactTool from builtin-tools barrel
**Files:**
- Modify: `packages/builtin-tools/src/index.ts`
- [ ] **Step 1: Read barrel to find an insertion point**
```bash
grep -n "SendUserFile" packages/builtin-tools/src/index.ts
```
- [ ] **Step 2: Add the export (insert after the SendUserFileTool line, keep alphabetical/grouped ordering)**
Add this single line next to the other tool exports:
```typescript
export { ArtifactTool } from './tools/ArtifactTool/ArtifactTool.js'
```
- [ ] **Step 3: Verify export works**
```bash
bun -e "import('@claude-code-best/builtin-tools').then(m => console.log(typeof m.ArtifactTool))"
```
Expected output: `object` (the built tool).
- [ ] **Step 4: Commit**
```bash
git add packages/builtin-tools/src/index.ts
git commit -m "feat(artifact): export ArtifactTool from builtin-tools barrel"
```
---
## Task 7: Register ArtifactTool in src/tools.ts
**Files:**
- Modify: `src/tools.ts`
- [ ] **Step 1: Add the require import (place near other non-feature-gated tools)**
Find a clean spot in the top section (near other `const X = require(...)` declarations) and add:
```typescript
const ArtifactTool = require('@claude-code-best/builtin-tools/tools/ArtifactTool/ArtifactTool.js').ArtifactTool
```
- [ ] **Step 2: Spread into the tools array (find the main returned array and add ArtifactTool unconditionally)**
Add `ArtifactTool,` to the array literal that returns the assembled tool list (e.g. next to `BriefTool,`).
- [ ] **Step 3: Verify by importing**
```bash
bun -e "import('./src/tools.js').then(m => { const t = (m.getTools ?? m.tools); const arr = typeof t === 'function' ? t({mode:'default',additionalWorkingDirectories:new Set(),alwaysAllowRules:{deny:[],allow:[]},alwaysDenyRules:{deny:[],allow:[]},alwaysAskRules:{deny:[],allow:[]},isBypassPermissionsModeAvailable:false}) : t; console.log(arr.map(x=>x.name).includes('artifact')) })"
```
If the dynamic shape is hard to invoke, instead just typecheck:
```bash
bunx tsc --noEmit -p tsconfig.json 2>&1 | head -50
```
Expected: no new errors mentioning ArtifactTool.
- [ ] **Step 4: Commit**
```bash
git add src/tools.ts
git commit -m "feat(artifact): register ArtifactTool in tools list"
```
---
## Task 8: /use-artifacts bundled skill
**Files:**
- Create: `src/skills/bundled/useArtifacts.ts`
- Modify: `src/skills/bundled/index.ts`
- [ ] **Step 1: Write the skill file**
```typescript
// src/skills/bundled/useArtifacts.ts
import { registerBundledSkill } from '../bundledSkills.js'
const USE_ARTIFACTS_PROMPT = `# Using Artifacts
Artifacts are public HTML pages you upload to a hosting service. They have stable URLs that you can share with the user or open in a browser. Use them to surface work-in-progress, summaries, and reports.
## When to use artifacts
**Good artifact content:**
- Progress panels / kanbans (task list with status)
- Research reports and analysis (data + findings + recommendations)
- Design docs / decision records (with context and rationale)
- Data visualizations (tables, SVG charts, flow diagrams)
- Final deliverables (the "thing the user asked for" rendered as HTML)
**Do NOT use artifacts for:**
- Code snippets — use files directly
- One-line answers — keep them in chat
- Internal debug logs — keep them in chat
- Large data dumps — link to source files instead
## Cadence — when to upload
- **Task start**: if the task is complex (multi-step, research, deliverable), upload a skeleton artifact first as scaffolding (placeholder sections).
- **Milestones**: when you complete a phase (research done / implementation done / tests pass), update the artifact.
- **User asks**: upload immediately.
- **Task end**: ship the final artifact as the deliverable.
**Do NOT upload:**
- After every tool call (noise)
- Mid-step with no meaningful change (e.g. fixed a typo)
## How to invoke (deferred tool)
\`artifact\` is a deferred tool. The first call requires two steps; subsequent calls one step.
**First upload (creates a new artifact):**
\`\`\`
1. Use the Write tool to write HTML to a local file (location is your choice).
2. SearchExtraTools({ query: "select:artifact" }) // loads the tool schema
3. ExecuteExtraTool({ tool_name: "artifact", params: { file_path: ".html" } })
4. Save the returned \`id\` from the tool result — this is the hash.
\`\`\`
**Subsequent updates (overwrites in place, URL stays stable):**
\`\`\`
1. Update the local HTML file.
2. ExecuteExtraTool({ tool_name: "artifact", params: { file_path: ".html", hash: "" } })
\`\`\`
The URL returned on every call is the same when you pass the same \`hash\`. The user can open it at any time to see the latest version.
## Minimal HTML skeleton
\`\`\`html
Artifact Title
Artifact Title
\`\`\`
The hosting service serves the HTML verbatim (including any \`