Worker SDKs

CodeBook provides TypeScript/JavaScript and Python clients for outside workers. The packages live in the CodeBook app repository; they are not published to a package registry yet.

Connect a worker

Create an external pull runtime in your factory, assign it to a station, and allow external execution in the factory policy. Enable the workflow API and create a separate write token for each worker in the workflow Share dialog. Use the MCP endpoint displayed there.

From a checkout of the app repository:

npm install ./sdk/typescript
python3 -m pip install ./sdk/python

Keep CODEBOOK_MCP_ENDPOINT and CODEBOOK_WORKER_TOKEN in your worker's environment. The token grants access to one workflow. It does not grant SSO administration or expose model-provider credentials.

import { CodeBookWorker } from '@codebook/worker';
const worker = new CodeBookWorker({
  endpoint: process.env.CODEBOOK_MCP_ENDPOINT,
  token: process.env.CODEBOOK_WORKER_TOKEN,
});
const { work } = await worker.listWork();
const item = work.find(item => !item.claimed || item.claimed_by_you);
if (item) {
  const { brief } = await worker.claimWork(item.run);
  await worker.startRun(item.run);
  // Your runtime executes and verifies the work described by brief.
  await worker.requestHuman(item.run, 'Please review the output before accepting it.');
}

Python uses CodeBookWorker from codebook_worker, with methods such as list_work, claim_work, start_run and request_human. See the repository SDK README for both complete examples and the method reference.

Progress, outputs and completion

• Send heartbeat while working. It updates liveness without extending the runtime deadline.
• Read getContext or getMemory after claiming a run. Canary station instructions remain frozen; card discussion and artifacts reflect current data.
• Add progress with comment and typed outputs with produceArtifact. Output kinds come from the brief's artifact_kinds.
• Report cumulative tokens with reportUsage. Repeating an earlier total never counts the same tokens twice. This is operational usage, not a charge to SSO billing.
• Finish with pass, fail or block and an evidence summary. Python calls a passing result pass_work because pass is a language keyword. Completion still goes through CodeBook's contracts, evaluations and routes.
• Use requestHuman to park the run for an authorized person's accept/reject decision. It stops the outside worker's control; it does not automatically resume after a chat answer.

Failures and retries

Clients have request timeouts and surface HTTP, protocol and tool errors. They refuse redirects so a token is not forwarded to another endpoint. Deleting the token or disabling workflow API access revokes future requests.

Clients do not automatically retry writes. Claims and start calls are repeatable by the same token, cumulative usage is safe to repeat, and identical artifacts return the saved output. Comments are append-only: inspect the card after an uncertain response before retrying. Do not complete work after requesting human review.

Check a deployed factory

sdk/typescript/scripts/deployed-check.mjs proves the SDK against a deployed factory with one real run through the whole lifecycle. Set CODEBOOK_MCP_ENDPOINT and CODEBOOK_WORKER_TOKEN (a write token created by a signed-in person in the workflow's Share dialog), queue a run by moving a test card into the station the pull runtime works, and run the script with an optional run ID.

It claims one run, starts it, sends a heartbeat, reads context and memory, comments, attaches a small artifact of a kind the brief allows, reports usage only if CODEBOOK_REPORT_TOKENS is set, and then calls request_human. It never passes work by itself: a person accepts or rejects the run in CodeBook afterwards, and nothing is built. The token is read from the environment and never printed. The same script runs in the SDK's automated test against the real MCP dispatcher.

.NET and Java clients follow after the TypeScript and Python clients prove the lifecycle API. These SDK languages do not restrict what programming languages a worker can edit.