{ "slug": "pilot/sdk/solid", "title": "Pilot SolidJS SDK", "description": "SolidJS primitives and components for Cuitty Pilot — reactive playbook management, run control, and real-time event streaming.", "url": "https://cuitty.com/docs/pilot/sdk/solid", "markdown_url": "https://cuitty.com/docs/pilot/sdk/solid.md", "json_url": "https://cuitty.com/docs/pilot/sdk/solid.json", "frontmatter": { "title": "Pilot SolidJS SDK", "description": "SolidJS primitives and components for Cuitty Pilot — reactive playbook management, run control, and real-time event streaming.", "order": 13, "section": "Pilot", "updatedAt": "2026-06-01" }, "headings": [ { "depth": 1, "slug": "pilot-solidjs-sdk", "text": "Pilot SolidJS SDK" }, { "depth": 2, "slug": "install", "text": "Install" }, { "depth": 2, "slug": "quick-start", "text": "Quick start" }, { "depth": 2, "slug": "pilotprovider", "text": "PilotProvider" }, { "depth": 3, "slug": "usepilot", "text": "usePilot()" }, { "depth": 2, "slug": "primitives", "text": "Primitives" }, { "depth": 3, "slug": "createplaybooksoptions", "text": "createPlaybooks(options?)" }, { "depth": 3, "slug": "createrun", "text": "createRun()" }, { "depth": 3, "slug": "createruneventsrunid", "text": "createRunEvents(runId)" }, { "depth": 2, "slug": "components", "text": "Components" }, { "depth": 3, "slug": "runstatusbadge", "text": "RunStatusBadge" }, { "depth": 3, "slug": "runtimeline", "text": "RunTimeline" }, { "depth": 3, "slug": "playbookcard", "text": "PlaybookCard" }, { "depth": 2, "slug": "error-handling", "text": "Error handling" }, { "depth": 2, "slug": "see-also", "text": "See also" } ], "body_markdown": "# Pilot SolidJS SDK\n\n`@cuitty/pilot-solid` provides SolidJS primitives and components for the Pilot API. It wraps `@cuitty/pilot-sdk` with idiomatic Solid patterns — context providers, `createResource` for data fetching, signals for run state, and automatic SSE cleanup.\n\n## Install\n\n```bash\nsfw bun add @cuitty/pilot-solid\n# or\nsfw npm install @cuitty/pilot-solid\n```\n\nPeer dependencies: `solid-js>=1.8`, `@cuitty/pilot-sdk`.\n\n## Quick start\n\n```tsx\nimport { PilotProvider, createPlaybooks, createRun, createRunEvents } from \"@cuitty/pilot-solid\";\nimport { For, Show, createSignal } from \"solid-js\";\n\nfunction App() {\n return (\n \n \n \n );\n}\n\nfunction Dashboard() {\n const [playbooks] = createPlaybooks();\n const [run, { start }] = createRun();\n const events = createRunEvents(() => run()?.id);\n\n return (\n
\n \n {(pb) => (\n \n )}\n \n \n {(e) =>
{e.type} {e.stepId}
}\n \n
\n );\n}\n```\n\n## PilotProvider\n\nWraps your component tree with a `PilotClient` instance. Accepts all `PilotClientConfig` props plus `children`. The client is closed automatically via `onCleanup`.\n\n```tsx\nimport { PilotProvider } from \"@cuitty/pilot-solid\";\n\n\n {props.children}\n\n```\n\n| Prop | Type | Description |\n|------|------|-------------|\n| `baseUrl` | `string` | Pilot server URL |\n| `auth` | `{ token?: string; cookie?: string; apiKey?: string }` | Authentication credentials |\n| `timeout` | `number` | Per-request timeout in ms (default 30000) |\n| `children` | `JSX.Element` | Child components |\n\n### usePilot()\n\nReturns the `PilotClient` from context. Throws if used outside ``.\n\n```tsx\nimport { usePilot } from \"@cuitty/pilot-solid\";\n\nconst pilot = usePilot();\nconst health = await pilot.health();\n```\n\n## Primitives\n\n### createPlaybooks(options?)\n\nReactive resource for listing playbooks. Wraps Solid's `createResource` — re-fetches when the options accessor changes.\n\n```tsx\nconst [playbooks, { refetch }] = createPlaybooks();\nconst [cfOnly] = createPlaybooks(() => ({ target: \"cloudflare\" }));\n```\n\n| Param | Type | Description |\n|-------|------|-------------|\n| `opts` | `() => ListPlaybooksOptions \\| undefined` | Optional accessor returning filter options |\n\nReturns a Solid `Resource` tuple: `[accessor, { refetch, mutate }]`.\n\n### createRun()\n\nManages a single run lifecycle with signals for run state and loading.\n\n```tsx\nconst [run, { start, abort, loading }] = createRun();\n\n// Start a new run\nconst result = await start({\n playbookId: \"cloudflare.dns.add-a-record\",\n mode: \"interactive\",\n inputs: { zone: \"example.com\", record_name: \"api\", ip_address: \"1.2.3.4\" },\n});\n\n// Abort the active run\nawait abort();\n```\n\n| Return | Type | Description |\n|--------|------|-------------|\n| `run` | `Accessor` | Signal with the current run object |\n| `start(req)` | `(StartRunRequest) => Promise` | Start a run and fetch its full details |\n| `abort()` | `() => Promise` | Abort the current run |\n| `loading` | `Accessor` | Signal, `true` while starting |\n\n### createRunEvents(runId)\n\nSubscribes to real-time SSE events for a run. Automatically unsubscribes via `onCleanup` and re-subscribes when `runId` changes.\n\n```tsx\nconst events = createRunEvents(() => run()?.id);\n\n// events is Accessor\n\n {(event) => {event.type}}\n\n```\n\n| Param | Type | Description |\n|-------|------|-------------|\n| `runId` | `() => string \\| null \\| undefined` | Accessor returning the run ID; `null`/`undefined` pauses subscription |\n\nReturns `Accessor` — accumulates all events since subscription started.\n\n## Components\n\n### RunStatusBadge\n\nRenders a colored pill badge for a run status.\n\n```tsx\nimport { RunStatusBadge } from \"@cuitty/pilot-solid\";\n\n\n\n```\n\nSupported statuses: `queued`, `running`, `awaiting_approval`, `completed`, `failed`, `aborted`.\n\n### RunTimeline\n\nRenders a vertical timeline of run events using ``, with color-coded borders (blue for in-progress, green for complete, red for failures). Uses `` for conditional step ID display.\n\n```tsx\nimport { RunTimeline } from \"@cuitty/pilot-solid\";\n\nconst events = createRunEvents(() => runId);\n\n```\n\n### PlaybookCard\n\nDisplays a playbook summary card with an optional \"Run\" button. Uses `` to conditionally render the button.\n\n```tsx\nimport { PlaybookCard } from \"@cuitty/pilot-solid\";\n\n start({ playbookId: pb.id, mode: \"autonomous\" })}\n/>\n```\n\n| Prop | Type | Description |\n|------|------|-------------|\n| `playbook` | `PlaybookSummary` | Playbook to display |\n| `onRun` | `(playbook: PlaybookSummary) => void` | Optional callback when \"Run\" is clicked |\n\n## Error handling\n\nErrors in `createPlaybooks` surface through the resource's error state. For `createRun`, errors thrown during `start()` propagate to the caller. For direct `PilotClient` usage via `usePilot()`, catch typed errors from `@cuitty/pilot-sdk`.\n\n```tsx\nimport { PilotApiError, PilotConnectionError } from \"@cuitty/pilot-sdk\";\n\nconst pilot = usePilot();\ntry {\n await pilot.runs.start({ playbookId: \"nonexistent\" });\n} catch (err) {\n if (err instanceof PilotApiError) {\n console.error(`API ${err.status}: ${err.statusText}`, err.body);\n } else if (err instanceof PilotConnectionError) {\n console.error(\"Cannot reach Pilot:\", err.message);\n }\n}\n```\n\n## See also\n\n- [JavaScript SDK](/docs/pilot/sdk/javascript) — underlying `PilotClient` API reference\n- [Playbook reference](/docs/pilot/playbook-reference) — YAML schema for playbook documents\n- [Quickstart](/docs/pilot/quickstart) — record and replay your first workflow", "body_html": "

Pilot SolidJS SDK

\n

@cuitty/pilot-solid provides SolidJS primitives and components for the Pilot API. It wraps @cuitty/pilot-sdk with idiomatic Solid patterns — context providers, createResource for data fetching, signals for run state, and automatic SSE cleanup.

\n

Install

\n
sfw bun add @cuitty/pilot-solid\n# or\nsfw npm install @cuitty/pilot-solid
\n

Peer dependencies: solid-js>=1.8, @cuitty/pilot-sdk.

\n

Quick start

\n
import { PilotProvider, createPlaybooks, createRun, createRunEvents } from \"@cuitty/pilot-solid\";\nimport { For, Show, createSignal } from \"solid-js\";\n\nfunction App() {\n  return (\n    <PilotProvider baseUrl=\"http://localhost:4320\" auth={{ apiKey: \"pk_...\" }}>\n      <Dashboard />\n    </PilotProvider>\n  );\n}\n\nfunction Dashboard() {\n  const [playbooks] = createPlaybooks();\n  const [run, { start }] = createRun();\n  const events = createRunEvents(() => run()?.id);\n\n  return (\n    <div>\n      <For each={playbooks()}>\n        {(pb) => (\n          <button onClick={() => start({ playbookId: pb.id, mode: \"autonomous\" })}>\n            {pb.title}\n          </button>\n        )}\n      </For>\n      <For each={events()}>\n        {(e) => <div>{e.type} {e.stepId}</div>}\n      </For>\n    </div>\n  );\n}
\n

PilotProvider

\n

Wraps your component tree with a PilotClient instance. Accepts all PilotClientConfig props plus children. The client is closed automatically via onCleanup.

\n
import { PilotProvider } from \"@cuitty/pilot-solid\";\n\n<PilotProvider\n  baseUrl=\"http://localhost:4320\"\n  auth={{ token: \"ey...\" }}\n  timeout={15000}\n>\n  {props.children}\n</PilotProvider>
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PropTypeDescription
baseUrlstringPilot server URL
auth{ token?: string; cookie?: string; apiKey?: string }Authentication credentials
timeoutnumberPer-request timeout in ms (default 30000)
childrenJSX.ElementChild components
\n

usePilot()

\n

Returns the PilotClient from context. Throws if used outside <PilotProvider>.

\n
import { usePilot } from \"@cuitty/pilot-solid\";\n\nconst pilot = usePilot();\nconst health = await pilot.health();
\n

Primitives

\n

createPlaybooks(options?)

\n

Reactive resource for listing playbooks. Wraps Solid’s createResource — re-fetches when the options accessor changes.

\n
const [playbooks, { refetch }] = createPlaybooks();\nconst [cfOnly] = createPlaybooks(() => ({ target: \"cloudflare\" }));
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ParamTypeDescription
opts() => ListPlaybooksOptions | undefinedOptional accessor returning filter options
\n

Returns a Solid Resource<PlaybookSummary[]> tuple: [accessor, { refetch, mutate }].

\n

createRun()

\n

Manages a single run lifecycle with signals for run state and loading.

\n
const [run, { start, abort, loading }] = createRun();\n\n// Start a new run\nconst result = await start({\n  playbookId: \"cloudflare.dns.add-a-record\",\n  mode: \"interactive\",\n  inputs: { zone: \"example.com\", record_name: \"api\", ip_address: \"1.2.3.4\" },\n});\n\n// Abort the active run\nawait abort();
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ReturnTypeDescription
runAccessor<Run | null>Signal with the current run object
start(req)(StartRunRequest) => Promise<Run | null>Start a run and fetch its full details
abort()() => Promise<void>Abort the current run
loadingAccessor<boolean>Signal, true while starting
\n

createRunEvents(runId)

\n

Subscribes to real-time SSE events for a run. Automatically unsubscribes via onCleanup and re-subscribes when runId changes.

\n
const events = createRunEvents(() => run()?.id);\n\n// events is Accessor<RunEvent[]>\n<For each={events()}>\n  {(event) => <span>{event.type}</span>}\n</For>
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ParamTypeDescription
runId() => string | null | undefinedAccessor returning the run ID; null/undefined pauses subscription
\n

Returns Accessor<RunEvent[]> — accumulates all events since subscription started.

\n

Components

\n

RunStatusBadge

\n

Renders a colored pill badge for a run status.

\n
import { RunStatusBadge } from \"@cuitty/pilot-solid\";\n\n<RunStatusBadge status=\"running\" />\n<RunStatusBadge status=\"completed\" />
\n

Supported statuses: queued, running, awaiting_approval, completed, failed, aborted.

\n

RunTimeline

\n

Renders a vertical timeline of run events using <For>, with color-coded borders (blue for in-progress, green for complete, red for failures). Uses <Show> for conditional step ID display.

\n
import { RunTimeline } from \"@cuitty/pilot-solid\";\n\nconst events = createRunEvents(() => runId);\n<RunTimeline events={events()} />
\n

PlaybookCard

\n

Displays a playbook summary card with an optional “Run” button. Uses <Show> to conditionally render the button.

\n
import { PlaybookCard } from \"@cuitty/pilot-solid\";\n\n<PlaybookCard\n  playbook={playbook}\n  onRun={(pb) => start({ playbookId: pb.id, mode: \"autonomous\" })}\n/>
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PropTypeDescription
playbookPlaybookSummaryPlaybook to display
onRun(playbook: PlaybookSummary) => voidOptional callback when “Run” is clicked
\n

Error handling

\n

Errors in createPlaybooks surface through the resource’s error state. For createRun, errors thrown during start() propagate to the caller. For direct PilotClient usage via usePilot(), catch typed errors from @cuitty/pilot-sdk.

\n
import { PilotApiError, PilotConnectionError } from \"@cuitty/pilot-sdk\";\n\nconst pilot = usePilot();\ntry {\n  await pilot.runs.start({ playbookId: \"nonexistent\" });\n} catch (err) {\n  if (err instanceof PilotApiError) {\n    console.error(`API ${err.status}: ${err.statusText}`, err.body);\n  } else if (err instanceof PilotConnectionError) {\n    console.error(\"Cannot reach Pilot:\", err.message);\n  }\n}
\n

See also

\n", "links_out": [ "/docs/pilot/sdk/javascript", "/docs/pilot/playbook-reference", "/docs/pilot/quickstart" ] }