Nightjar

Give Codex or Claude work from your backend. Submit a goal and receive a durable result or signed webhook.

Node.js 22+ · TypeScript · ESM + CommonJS · No runtime dependencies

Install

npm install @silicon-intern/nightjar

In the Nightjar dashboard, connect your own Codex or Claude account and create a key under Developers → API keys. Your backend only needs:

NIGHTJAR_API_KEY=your_workspace_key

import Nightjar from '@silicon-intern/nightjar';

const nightjar = new Nightjar();
const result = await nightjar.run('Return a short checklist for testing a signup flow.');
console.log(result.output);

No saved agent or workspace ID is required. The key identifies its workspace, and Nightjar selects the key creator's ready model account. For self-hosting, also set NIGHTJAR_BASE_URL. Account sign-in and tool authorization happen in the dashboard; API keys stay on your backend.

run waits for successful completion. Failed, cancelled, or needs-input runs throw NightjarRunError, with the snapshot in error.run. The upcoming conversation release also waits through pending publication and rejects failed deliverables. Named imports and CommonJS are supported.

Use your connected tools

With only the API key configured, runs receive no Nightjar service connections. Connect GitHub in the dashboard and select it in Developers → Quickstart to copy an example with its actual connection ID:

const result = await nightjar.run({
  prompt:
    'Summarize the last seven days of changes in the connected repository. Do not modify anything.',
  connectionIds: ['YOUR_GITHUB_CONNECTION_ID'],
});
console.log(result.output);

Replace the placeholder with your selected connection ID. Nightjar tool calls use the connection's saved permissions.

Submit now, collect later

const run = await nightjar.runs.create(
  {
    input: 'Return a short checklist for testing a signup flow.',
    metadata: { jobId: 'signup-checklist-001' },
  },
  { idempotencyKey: 'signup-checklist-001' },
);
// Save run.id, then collect a webhook or wait in a worker:
const result = await nightjar.runs.result(run.id);
console.log(result.output);

Recover an uncertain submission with the same body and idempotency key. timeoutMs limits local waiting; timeoutSeconds limits remote execution. A local timeout does not cancel the run. API keys stay on the server, and runs use the key creator's connected model account.

For structured output, pass a provider-compatible outputSchema and a runtime parse function. To receive webhooks, use parseWebhook from @silicon-intern/nightjar/webhooks on the exact raw request bytes and deduplicate by event ID. The guide includes complete examples.

SDK 1.2.0 also parses opt-in task.queued, task.started, and task.progress webhooks. Each new task envelope has runId, workspaceId, and a positive sequence for persisted activity order; deliveries can arrive out of order, so apply status changes only when their sequence is newer than the last processed status for that run. Deduplicate event.id across retries. Existing webhook subscriptions retain terminal events until you select additional event types.

Progress is a compact snapshot with data.task identity, status, and metadata, plus data.progress.type and data.progress.message. It reports provider messages, tool work, and runner activity without repeating the full output. Narrow event.type before reading task output; full snapshots are available on queued, started, and terminal events. Older terminal envelopes remain supported. See the signed webhook guide for verification and delivery behavior.

Install the SDK with lifecycle webhook support from npm:

npm install '@silicon-intern/nightjar@^1.2.0'

Saved agents remain optional for reusable instructions and defaults. Existing agentId, workspaceId, NIGHTJAR_AGENT_ID, and NIGHTJAR_WORKSPACE_ID settings are supported; leave them unset for the first-run examples above.

Download project files

Project ZIP downloads are included in the current npm SDK:

npm install '@silicon-intern/nightjar@^1.2.0'

import { writeFile } from 'node:fs/promises';

const result = await nightjar.runs.result(run.id);
const project = result.artifacts?.[0];
if (project) {
  const bytes = await nightjar.runs.downloadArtifact(result.id, project.id);
  await writeFile('./project.zip', bytes);
}
for (const delivery of result.github ?? []) {
  console.log(delivery.pullRequest?.url ?? delivery.branchUrl);
}

Downloads use your client's authentication and return a Uint8Array with a 25 MiB limit. signal, requestTimeoutMs, and maxRetries work as on other reads. Run snapshots and signed task webhooks optionally include artifacts, github, and artifactError; existing output and structuredOutput are unchanged. GitHub links represent verified repository work. The dashboard offers Download ZIP, View branch, and View PR, while Download summary saves the Markdown response.

Reference

The integration guide covers configuration, structured output, durable webhooks, retries, cancellation, cloud execution limits, and every SDK method. It ships at node_modules/@silicon-intern/nightjar/GUIDE.md for coding agents. See CHANGELOG.md for release changes.

To upgrade from [email protected], change the import path or use npm install 'nightjar-sdk@npm:@silicon-intern/nightjar@^1.0.0'. Existing named imports, runs APIs, legacy task methods, and verifyWebhook remain supported. runs.wait still returns unsuccessful stopped runs; runs.result throws for them.

Upcoming conversation support

SDK 1.3.0 adds runs.answer(id, {requestId, answer}), runs.recover(id), structured attention/lifecycle, and signed question, answer, recovery, and delivery updates. These methods and new event types require SDK 1.3.0 or later and the updated server; the 1.2.0 parser rejects the new event types.

Use lifecycle.resultReady to recognize a ready result and lifecycle.canAnswer to show a necessary question. Answer with the exact attention.id, then observe the returned continuation ID; repeating the same answer returns the same continuation. Ordinary background work needs no answer form. See questions, answers, and recovery for the complete flow and event subscriptions.