ambleloftBackground jobs API and outcomes
Host-managed, tool-free model jobs: submit frozen inputs, validate output against a schema and read results after completion events.
Browse contracts, signatures, fields and examples. Unspecified defaults are not inferred.
On this page
01Submit and get
Preview capability · SDK 0.1.0-alpha.9
submit returns a persisted job without waiting for model completion. get returns the saved state and result. Requires project-scoped background.jobs and authorized access to referenced turns.
interface BackgroundJobInput {
projectId: string; eventKey: string; prompt: string;
turns: TurnReference[]; outputSchema: JsonObject;
}
interface BackgroundJob {
id: string; eventKey: string; projectId: string;
status: 'queued' | 'running' | 'succeeded' | 'failed' | 'unknown' | 'cancelled';
providerId: string; model: string; createdAt: number; result?: Json; error?: string;
}
jobs.submit(input: BackgroundJobInput): Promise<BackgroundJob>;
jobs.get(jobId: string): Promise<BackgroundJob>;02States and recovery
Use the authoritative jobs.get state; a completion Hook alone is not evidence of success.
| Field / API | Contract |
|---|---|
| queued | Persisted; waiting for policy, grants, quota and execution slot. |
| running | Model request started; becomes unknown after restart. |
| succeeded | Output passed schema validation; inspect result. |
| failed | Request or output validation failed; inspect error. No automatic format-repair call. |
| unknown | Outcome cannot be confirmed; do not automatically resend with a new key. |
| cancelled | Queued job cancelled, for example by revocation. |
03Schema, limits and model calls
Output must match outputSchema. A single non-streaming Chat Completions / Responses request is made without tools, agent execution or execution of model-suggested actions. Invalid output fails without a repair request.
| Field / API | Contract |
|---|---|
| turns | 1–10 explicit references; frozen text at most 48,000 bytes. |
| prompt / input | Prompt up to 8,000 characters; submission JSON up to 24,000 bytes. |
| output | Up to 2,048 tokens; response up to 256 KB; request timeout 120 seconds. |
| budget | Rolling 24-hour budget defaults to 20 calls, range 1–100; failed/unknown calls count. |
04Idempotency and errors
eventKey is scoped to the extension installation: identical key and input returns the existing job; changed input produces CONFLICT. Limits return QUOTA_EXCEEDED or failure; inputs are not silently truncated. Disabling or revocation cancels queued jobs; existing results are not regenerated. Reconcile unknown outcomes in host management; explicit regeneration can charge again. Extensions cannot change policy, read credentials or invoke management cleanup/replay APIs.
05Exact retry representation
Deduplication hashes JSON.stringify(content) without sorting object keys. Reusing eventKey only reuses a job when that serialized content has the same hash; changed content conflicts. Keep the original request representation. For unknown, inspect the original job; do not change keys, reorder fields or automatically resubmit. Public jobs APIs are submit/get only, without cancel/retry/manage.