contextos-client 0.0.0-stage → 0.1.0-alpha.12

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,20 @@
+ContextOS
+Copyright 2026 The ContextOS Authors
+
+This product includes software developed as part of the ContextOS project
+(https://github.com/contextosai/ContextOS), licensed under the Apache License,
+Version 2.0 (see LICENSE).
+
+Third-party dependency licenses and attribution are in THIRD_PARTY_NOTICES.txt.
+
+conformance/reference/ includes the unmodified deterministic TypeScript reference
+and synthetic fixtures from contextosai/contextosai, revision
+7e2462fd931a79e3777ede81fb382e0cbf2ff46c.
+Copyright (c) 2025-2026 ContextOS; licensed under Apache-2.0.
+
+Documentation prose in docs/ and the Markdown guides is licensed under the
+Creative Commons Attribution 4.0 International license (see LICENSE-docs);
+code examples within it are licensed under Apache-2.0.
+
+"ContextOS" and its logo are trademarks of the ContextOS project; neither
+license grants rights to use them (see TRADEMARKS.md).

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# ContextOS for Node.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Two parts, published differently:
+
+- `contextos-client` on npm is the HTTP client for `contextosd` (`client.mjs`, with
+  TypeScript types in `client.d.ts`). It has no dependencies and runs anywhere `fetch`
+  does: Node.js 18 or newer, edge and serverless runtimes.
+- The in-process kernel (`index.mjs`, an N-API addon) is not published. Build it from
+  this repository only if you embed the kernel without a server.
+
+## The HTTP client
+
+```sh
+npm install contextos-client
+```
+
+```ts
+import { Client, ToolPaused, ToolBlocked, governedTool } from "contextos-client";
+
+const client = new Client("https://contextos.internal", { token: process.env.CONTEXTOS_TOKEN! });
+const run = await client.admit(admissionBody);   // holds the executor generation
+const output = await run.callTool("adp_payments.issue_refund", args,
+  { approvalMode: "destructive", idempotencyKey: "refund:ord_881", evidenceRefs });
+```
+
+Results that are not plain success throw: `ToolPaused` (approval, input, or an unknown
+outcome to reconcile: never retry blindly), `ToolBlocked`, `ToolRejected`,
+`ToolFailed`. Only requests the server did not process (429, 503) are retried.
+
+Try it against a local server from a checkout: `./examples/dev-server.sh` prints
+`CONTEXTOS_URL` and `CONTEXTOS_TOKEN`. The
+[integration guides](https://github.com/contextosai/ContextOS/tree/main/docs/integrations)
+show the client inside Mastra, the Vercel AI SDK and the OpenAI Agents SDK.
+
+The client's version matches the `contextosd` release it was published with. Use the
+same release on both sides while ContextOS is in alpha: before its first admission the
+client emits a `VersionMismatchWarning` when the server is another release, and throws
+`IncompatibleServer` for a server with another API generation. `checkServer: false`
+skips the check.
+
+## The embedded kernel
+
+```sh
+cargo build --release -p contextos-node
+cp target/release/libcontextos_node.so bindings/node/contextos.node   # .dylib on macOS
+```
+
+```js
+import { kernel } from "./bindings/node/index.mjs";
+const compiled = await kernel.call("compile", { pack, request, run_context });
+```
+
+`CONTEXTOS_NATIVE` overrides the addon's path.

package/client.d.ts

@@ -0,0 +1,286 @@
+export declare const GENERATION_HEADER: "ContextOS-Executor-Generation";
+
+export type ApprovalMode = "read_only" | "local_write" | "network" | "delegated" | "destructive";
+export type DecisionStatus = "DECIDED" | "DEFERRED" | "REJECTED" | "ESCALATED" | "IN_FLIGHT" | "CLOSED";
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+
+export type RevocationKind = "tenant" | "pack" | "agent" | "adapter" | "capability";
+export interface Revocations {
+  revoked: { kind: RevocationKind; target: string; reason: string; by: string; at: string }[];
+}
+
+export interface DispatchReport {
+  status: string;
+  action_digest: string | null;
+  operation_id: string | null;
+  attempt_id: string | null;
+  reason_codes: string[];
+  obligations: string[];
+  approval_request_id: string | null;
+  audit_sequences: number[];
+}
+
+export declare const RUN_HEADER: string;
+export declare const CLIENT_VERSION: string;
+export declare const API_VERSION: "v1";
+
+export interface ServerVersions {
+  apiVersion: string | null;
+  runtimeVersion: string | null;
+  clientVersion: string;
+}
+/** The server speaks a different HTTP API generation than this client. */
+export declare class IncompatibleServer extends Error {}
+export declare function checkVersions(deployment: unknown, clientVersion?: string): ServerVersions;
+export declare const RESERVATION_HEADER: string;
+
+export declare class ContextOSHTTPError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly detail: unknown;
+}
+
+/** A model-call or replan reservation the run's budget cannot fit; stop the loop. */
+export declare class BudgetExhausted extends ContextOSHTTPError {
+  readonly reasons: string[];
+}
+
+export declare class ToolOutcome extends Error {
+  readonly result: Record<string, Json>;
+  readonly report: DispatchReport;
+  readonly status: string;
+  readonly reasonCodes: string[];
+  readonly obligations: string[];
+  readonly operationId: string | null;
+}
+/** A team finding: a claim, or an observation bound to a recorded tool call. */
+export interface Finding {
+  finding_id: string;
+  kind: "claim" | "observed";
+  statement: string;
+  depends_on: string[];
+  urgent: boolean;
+  basis: { run_id: string; operation_id: string; action_digest: string; capability_ref: Json; outcome: "confirmed"; observation_ref: Json; observed_at: string } | null;
+  refutes: string | null;
+  author_run_id: string;
+  created_at: string;
+  status: "active" | "suspect" | "invalidated";
+  suspect_because: string[];
+  invalidation: { by_run_id: string; at: string; reason: string; refuted_by: string | null } | null;
+}
+
+export interface Notice {
+  seq: number;
+  kind: "finding_invalidated" | "finding_published";
+  finding_id: string;
+  by_run_id: string;
+  at: string;
+  excerpt: string;
+  suspect: string[];
+  suspect_count: number;
+}
+
+export interface NoticeView {
+  notices: Notice[];
+  pending: number;
+  missed: boolean;
+  acknowledged_seq: number;
+  latest_seq: number;
+  data_only: true;
+}
+
+/** An effect whose capability declares compensation, and where it stands. */
+export interface CompensableEffect {
+  operation_id: string;
+  capability_id: string;
+  compensator: string;
+  outcome: string;
+  compensation_operation_id: string;
+  compensation_outcome: string;
+  state: "compensable" | "compensated" | "partially_compensated" | "compensating" | "compensation_exhausted" | "unresolved" | "not_applied";
+}
+
+/** Approval pending, input required, or an unknown outcome to reconcile. Never retry blindly. */
+export declare class ToolPaused extends ToolOutcome {
+  /**
+   * What the pause waits on: `approval` (re-send the same call once approved), `input`
+   * (answer with provideInput), `unknown_outcome` (the effect may have happened:
+   * reconcile), `duplicate` (already requested; not repeated) or `other`.
+   */
+  readonly kind: "approval" | "input" | "unknown_outcome" | "duplicate" | "other";
+  readonly inputRequests: Record<string, Json> | null;
+}
+/** Authority, policy, constraints or budget refused the call. */
+export declare class ToolBlocked extends ToolOutcome {}
+/** Malformed, not surfaced to this run, or incompatible reuse of an operation key. */
+export declare class ToolRejected extends ToolOutcome {}
+/** The provider definitively did not apply the effect. */
+export declare class ToolFailed extends ToolOutcome {}
+
+export interface CallOptions {
+  approvalMode?: ApprovalMode;
+  idempotencyKey?: string | null;
+  evidenceRefs?: string[];
+  toolCallId?: string;
+}
+
+export declare class Client {
+  constructor(baseUrl: string, options: { token: string; timeoutMs?: number; maxRetries?: number; fetch?: typeof fetch; checkServer?: boolean });
+  /** Reads GET /v1/deployment: throws IncompatibleServer on another API generation, warns on another release. Runs once before the first admit. */
+  checkServer(): Promise<ServerVersions>;
+  readonly baseUrl: string;
+  request<T = any>(method: string, path: string, options?: { body?: unknown; generation?: number; query?: Record<string, string | number> }): Promise<T>;
+  admit(body: Record<string, any>, options?: { principalChain?: { kind: string; id: string }[] }): Promise<Run>;
+  attach(runId: string, traceId: string, principalChain: { kind: string; id: string }[]): Promise<Run>;
+  /** Scores a recorded decision as an independent evaluator (token with only `evaluate`). */
+  amendTaskAuthorization(runId: string, expectedRevision: number, task: Json): Promise<{ run_id: string; revision: number; change: "narrowed" | "widened"; task_authorization_ref: Json; policy_refs: Json[] }>;
+  score(runId: string, recordId: string, scores: { evaluatorRef: string; policy: number; utility: number; safety: number }): Promise<{ score: Record<string, any>; audit_sequence: number }>;
+  /** Files an operator correction or override against a run (token with `evaluate`, independent of the run). */
+  fileFeedback(runId: string, feedback: { kind: "correction" | "override" | "approval_verdict"; targetSurface: FeedbackSurface; summary: string; decisionRecordId?: string; expectedOutcome?: string }): Promise<Feedback>;
+  /** The tenant's open policy escalations, oldest first. */
+  openEscalations(options?: { limit?: number }): Promise<{ open: number; escalations: Record<string, Json>[] }>;
+  /** Records how a human resolved an escalation (token with `control`); grants nothing. */
+  resolveEscalation(escalationId: string, resolution: "handled" | "dismissed", reason: string): Promise<Record<string, Json>>;
+  /** The tenant's open feedback, oldest first. */
+  openFeedback(options?: { limit?: number }): Promise<{ open: number; feedback: Feedback[] }>;
+  /** Closes feedback with a reference to the evidence (token with `control`). */
+  closeFeedback(feedbackId: string, status: "fixed" | "still_failing" | "invalid" | "superseded", evidence: { artifactType: string; artifactId: string; sha256: string }): Promise<Feedback>;
+  /** Kill switch (token with the `control` scope). */
+  revoke(kind: RevocationKind, target: string, reason: string): Promise<Revocations>;
+  restore(kind: RevocationKind, target: string, reason: string): Promise<Revocations>;
+  revocations(): Promise<Revocations>;
+  auditEntries(options?: { from?: number; page?: number }): AsyncGenerator<Record<string, Json>>;
+}
+
+export type FeedbackSurface = "run_context" | "pack" | "policy" | "tool" | "memory" | "skill" | "evaluator" | "unknown";
+
+export interface Feedback {
+  feedback_id: string;
+  run_id: string;
+  trace_id: string;
+  decision_record_id: string | null;
+  kind: string;
+  target_surface: FeedbackSurface;
+  summary: string;
+  expected_outcome: string | null;
+  reporter: string;
+  filed_at: string;
+  status: "open" | "fixed" | "still_failing" | "invalid" | "superseded";
+  replay_obligation: { case: string; replay_case: string };
+  closed_at?: string;
+  closed_by?: string;
+  evidence_ref?: { artifact_type: string; artifact_id: string; sha256: string };
+}
+
+export interface WorkEvidence { artifact_type: string; artifact_id: string; sha256: string }
+export interface WorkClaim { run_id: string; executor_generation: number; lease_epoch: number; expires_at: string }
+export interface WorkTask {
+  task_id: string; title: string; acceptance_criteria: string; dependencies: string[];
+  created_by_run_id: string; created_at: string; revision: number; lease_epoch: number;
+  status: "pending" | "claimed" | "completed"; claim: WorkClaim | null; previous_claim: WorkClaim | null;
+  evidence_refs: WorkEvidence[]; dependencies_ready: boolean; available: boolean; lease_expired: boolean;
+}
+export type WorkCommand =
+  | { action: "claim"; expected_revision: number; lease_seconds: number }
+  | { action: "renew"; expected_revision: number; lease_epoch: number; lease_seconds: number }
+  | { action: "release"; expected_revision: number; lease_epoch: number }
+  | { action: "complete"; expected_revision: number; lease_epoch: number; evidence_refs: WorkEvidence[] };
+/** Advisory worker metadata; evidence refs are not independently verified. */
+export interface WorkResult { root_run_id: string; task: WorkTask; data_only: true; evidence_verified: false }
+export interface WorkPage { root_run_id: string; tasks: WorkTask[]; next_cursor: string | null; data_only: true; evidence_verified: false }
+
+export declare class Run {
+  readonly client: Client;
+  readonly runId: string;
+  readonly traceId: string;
+  executorGeneration: number;
+  readonly principalChain: { kind: string; id: string }[];
+  envelope(capabilityId: string, args: Record<string, Json>, options?: CallOptions): Record<string, Json>;
+  callTool(capabilityId: string, args: Record<string, Json>, options?: CallOptions): Promise<Record<string, Json>>;
+  provideInput(paused: ToolPaused, envelope: Record<string, Json>, responses: Record<string, Json>): Promise<Record<string, Json>>;
+  reconcile(operationId: string, options?: { outcome?: "confirmed" | "not_applied" | "partial"; evidenceRef?: Record<string, string> }): Promise<any>;
+  /** Relays an outcome witness's signed reading (compact JWS); needs `outcome:report`. */
+  reportOutcome(operationId: string, attestation: string): Promise<{ run_id: string; operation_id: string; state: "witnessed"; postcondition: string; late: boolean; observation: Record<string, Json> }>;
+  compensations(): Promise<{ run_id: string; effects: CompensableEffect[] }>;
+  compensate(operationId: string, options?: { toolCallId?: string }): Promise<Record<string, Json>>;
+  compensateAll(): Promise<{ run_id: string; status: "compensated" | "stopped"; steps: { operation_id: string; result: any; report: any }[]; stopped_at: { operation_id: string; reason: string } | null }>;
+  recordDecision(decisionKey: string, status: DecisionStatus, options?: { decisionVersion?: string; outcome?: string; toolCalls?: { tool_call_id: string; operation_id: string }[]; [field: string]: unknown }): Promise<{ record: any; replay_packet: any }>;
+  delegate(childAdmission: Record<string, any>, envelope: Record<string, any>): Promise<Run>;
+  closeChild(child: Run, decision?: "accept" | "reject"): Promise<{ status: string; usage: Record<string, number> | null; reason_codes: string[] }>;
+  checkpoint(state: Json, expectedRevision: number): Promise<{ run_id: string; revision: number; digest: string; executor_generation: number; saved_at: string }>;
+  latestCheckpoint(): Promise<{ revision: number; digest: string; state: Json; executor_generation: number; saved_at: string }>;
+  publishWork(taskId: string, title: string, acceptanceCriteria: string, options?: { dependencies?: string[] }): Promise<WorkResult>;
+  workTasks(options?: { after?: string; limit?: number }): Promise<WorkPage>;
+  workTask(taskId: string): Promise<WorkResult>;
+  updateWork(taskId: string, command: WorkCommand): Promise<WorkResult>;
+  /** Peer notices that came with the latest tool result (peer data, never instructions). */
+  lastNotices: NoticeView | null;
+  publishFinding(findingId: string, statement: string, options?: { kind?: "claim" | "observed"; dependsOn?: string[]; basisOperationId?: string; basisRunId?: string; refutes?: string; urgent?: boolean }): Promise<{ root_run_id: string; finding: Finding; data_only: true }>;
+  findings(options?: { after?: string; limit?: number }): Promise<{ root_run_id: string; findings: Finding[]; next_cursor: string | null; data_only: true }>;
+  invalidateFinding(findingId: string, reason: string, options?: { refutedBy?: string }): Promise<{ root_run_id: string; finding: Finding; suspect: string[]; data_only: true }>;
+  notices(options?: { limit?: number }): Promise<NoticeView & { root_run_id: string }>;
+  ackNotices(through: number): Promise<NoticeView>;
+  reserveUsage(kind: "model_call" | "replan", options?: { tokens?: number; costCents?: number }): Promise<string>;
+  settleUsage(reservationId: string): Promise<{ reservation_id: string; charged: Record<string, number>; verified: boolean }>;
+  /** Headers for a model request that a metering LLM gateway settles with the usage it measures. */
+  meteringHeaders(reservationId: string): Record<string, string>;
+  /**
+   * Reserves budget around one model call and settles it afterwards; throws BudgetExhausted first if it
+   * cannot fit. `metered` leaves settlement to a metering LLM gateway unless the call throws.
+   */
+  budgetedModelCall<T>(
+    fn: (reservationId: string) => Promise<T>,
+    options: { tokens: number; costCents?: number; metered?: boolean },
+  ): Promise<T>;
+  status(): Promise<{ run_id: string; status: string; executor_generation: number }>;
+  takeOver(): Promise<Run>;
+  complete(): Promise<any>;
+  fail(): Promise<any>;
+  cancel(): Promise<any>;
+  evidence(): Promise<any>;
+}
+
+export declare function governedTool<A extends Record<string, Json>>(
+  run: Run,
+  capabilityId: string,
+  options?: {
+    approvalMode?: ApprovalMode;
+    idempotencyKey?: (args: A) => string;
+    evidenceRefs?: string[];
+    toolCallId?: (args: A) => string;
+  },
+): (args: A) => Promise<Record<string, Json>>;
+
+export interface PrincipalRef {
+  principal_id: string;
+  principal_type: "person" | "workload" | "agent";
+  trust_domain: string;
+  tenant_id: string;
+}
+
+export declare function taskScope(
+  rootRunId: string,
+  purposeId: string,
+  capabilityId: string,
+  options?: {
+    resources?: string[];
+    destinations?: string[];
+    classification?: string;
+    amount?: [number, string];
+    argumentConstraints?: Json[];
+  },
+): Json;
+
+export declare function taskAuthorization(
+  issuedBy: PrincipalRef,
+  scopes: Json[],
+  options?: {
+    outOfScope?: "deny" | "ask";
+    readOnly?: "allow" | "scoped";
+    confirmationRef?: Json;
+    /** Most effects the whole task may make. */
+    maxEffects?: number;
+    /** Most the task's effects may move in total. */
+    amountTotal?: { minorUnits: number; currency: string };
+  },
+): Json;

package/client.mjs

@@ -0,0 +1,552 @@
+// HTTP client for contextosd: govern an agent's tool calls from Node.js or any
+// runtime with fetch. No dependencies and no native addon.
+//
+//   import { Client, ToolPaused, ToolBlocked, governedTool } from "contextos-client";
+//   const client = new Client("https://contextos.internal", { token: process.env.CONTEXTOS_TOKEN });
+//   const run = await client.admit(admissionBody);       // holds the executor generation
+//   const output = await run.callTool("adp_payments.issue_refund", args,
+//     { approvalMode: "destructive", idempotencyKey: "refund:ord_881", evidenceRefs });
+//
+// Results that are not plain success throw: ToolPaused (approval, input, or an
+// unknown outcome to reconcile — never retry blindly), ToolBlocked, ToolRejected,
+// ToolFailed. Only requests the server did not process (429, 503) are retried.
+
+export const GENERATION_HEADER = "ContextOS-Executor-Generation";
+// On a model request, these tell a metering LLM gateway which reservation to settle with
+// the usage it measures (see examples/metering-proxy).
+export const RUN_HEADER = "ContextOS-Run-Id";
+export const RESERVATION_HEADER = "ContextOS-Usage-Reservation";
+// This client's release (scripts/package_clients.py checks it against Cargo.toml) and
+// the HTTP API generation it speaks; a server reports both in GET /v1/deployment.
+export const CLIENT_VERSION = "0.1.0-alpha.12";
+export const API_VERSION = "v1";
+
+/** The server speaks a different HTTP API generation than this client. */
+export class IncompatibleServer extends Error {}
+
+function warnVersion(message) {
+  if (typeof globalThis.process?.emitWarning === "function") {
+    globalThis.process.emitWarning(message, "VersionMismatchWarning");
+  } else {
+    console.warn(`VersionMismatchWarning: ${message}`);
+  }
+}
+
+// Throws on a different API generation; warns on a different or unreported release.
+export function checkVersions(deployment, clientVersion = CLIENT_VERSION) {
+  const api = deployment?.api_version ?? null;
+  const runtime = deployment?.runtime_version ?? null;
+  if (api !== null && api !== API_VERSION) {
+    throw new IncompatibleServer(`contextosd speaks API ${api}; this client speaks ${API_VERSION}`);
+  }
+  if (runtime === null) {
+    warnVersion(`contextosd does not report its release (older than this client, ${clientVersion}); use the same release on both sides`);
+  } else if (runtime !== clientVersion) {
+    warnVersion(`contextosd is release ${runtime}; this client is ${clientVersion}. Use the same release on both sides`);
+  }
+  return { apiVersion: api, runtimeVersion: runtime, clientVersion };
+}
+
+export class ContextOSHTTPError extends Error {
+  constructor(status, code, message, detail) {
+    super(`${status} ${code}: ${message}`);
+    this.status = status;
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+/** The run's budget cannot fit a model-call or replan reservation; `reasons` says which
+ * limit. Stop the loop: retrying the same reservation cannot succeed. */
+export class BudgetExhausted extends ContextOSHTTPError {
+  get reasons() {
+    return Array.isArray(this.detail) ? this.detail : [];
+  }
+}
+const HTTP_ERRORS = { budget_exhausted: BudgetExhausted };
+
+export class ToolOutcome extends Error {
+  constructor(result, report) {
+    const reasons = report.reason_codes ?? [];
+    super(`${result.status}: ${reasons.join(", ") || result.error || ""}`);
+    this.result = result;
+    this.report = report;
+    this.status = result.status;
+    this.reasonCodes = reasons;
+    this.obligations = report.obligations ?? [];
+    this.operationId = report.operation_id ?? null;
+  }
+}
+export class ToolPaused extends ToolOutcome {
+  /** What the pause waits on; see client.d.ts. */
+  get kind() {
+    const { obligations: o, reasonCodes: r } = this;
+    if (o.includes("await_approval")) return "approval";
+    if (o.includes("provide_requested_input")) return "input";
+    if (o.includes("reconcile_effect_before_retry")) return "unknown_outcome";
+    if (r.includes("retry_unsafe") || o.includes("reconcile_existing_operation")) return "duplicate";
+    return "other";
+  }
+  get inputRequests() {
+    return this.result.output?.result?.inputRequests ?? null;
+  }
+}
+export class ToolBlocked extends ToolOutcome {}
+export class ToolRejected extends ToolOutcome {}
+export class ToolFailed extends ToolOutcome {}
+
+const OUTCOMES = { paused: ToolPaused, blocked: ToolBlocked, rejected: ToolRejected, failed: ToolFailed };
+
+function outcome(response) {
+  const { result, report } = response;
+  if (result.status === "ok" || result.status === "completed") return result.output ?? {};
+  throw new (OUTCOMES[result.status] ?? ToolOutcome)(result, report);
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const segment = (value) => {
+  if (value === "" || value === "." || value === "..") throw new TypeError(`invalid path segment ${JSON.stringify(value)}`);
+  return encodeURIComponent(value);
+};
+
+// Before its first admission the client reads GET /v1/deployment once: a server with
+// another API generation throws IncompatibleServer, another release warns
+// (VersionMismatchWarning). `checkServer: false` skips it.
+export class Client {
+  #token;
+  #serverChecked;
+
+  constructor(baseUrl, { token, timeoutMs = 30_000, maxRetries = 3, fetch: fetchImpl = globalThis.fetch, checkServer = true } = {}) {
+    if (!token) throw new TypeError("a token is required");
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.#token = token;
+    this.timeoutMs = timeoutMs;
+    this.maxRetries = maxRetries;
+    this.fetch = fetchImpl;
+    this.#serverChecked = checkServer ? null : Promise.resolve();
+  }
+
+  /** Compares the server's API generation and release with this client's. */
+  async checkServer() {
+    const versions = checkVersions(await this.request("GET", "/v1/deployment"));
+    this.#serverChecked = Promise.resolve();
+    return versions;
+  }
+
+  toJSON() {
+    return { baseUrl: this.baseUrl }; // never serialize the token
+  }
+
+  async request(method, path, { body, generation, query } = {}) {
+    let url = this.baseUrl + path;
+    if (query) url += "?" + new URLSearchParams(Object.entries(query).map(([k, v]) => [k, String(v)]));
+    const headers = { Authorization: `Bearer ${this.#token}`, Accept: "application/json" };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    if (generation !== undefined) headers[GENERATION_HEADER] = String(generation);
+    for (let attempt = 0; ; attempt++) {
+      const response = await this.fetch(url, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(this.timeoutMs),
+        redirect: "error",
+      });
+      const text = await response.text();
+      const decoded = text ? JSON.parse(text) : null;
+      if (response.ok) return decoded;
+      // Not processed: safe to retry after the server's hint.
+      if ((response.status === 429 || response.status === 503) && attempt < this.maxRetries) {
+        const hint = Number(response.headers.get("retry-after"));
+        await sleep(Number.isFinite(hint) && hint > 0 ? Math.min(hint, 30) * 1000 : Math.min(200 * 2 ** attempt, 5000));
+        continue;
+      }
+      const failure = decoded?.error;
+      if (failure && typeof failure === "object") {
+        const code = failure.code ?? "error";
+        throw new (HTTP_ERRORS[code] ?? ContextOSHTTPError)(response.status, code, failure.message ?? "", failure.detail);
+      }
+      throw new ContextOSHTTPError(response.status, "refused", text, decoded);
+    }
+  }
+
+  /** Admits a run (POST /v1/runs) and returns a handle that owns it. */
+  async admit(body, { principalChain } = {}) {
+    if (this.#serverChecked === null) {
+      // Concurrent first admissions share one check; a failed check is retried next time.
+      this.#serverChecked = this.checkServer().catch((error) => {
+        this.#serverChecked = null;
+        throw error;
+      });
+    }
+    await this.#serverChecked;
+    const admitted = await this.request("POST", "/v1/runs", { body });
+    const context = body.run_context ?? {};
+    const agent = context.agent?.agent_id;
+    return new Run(this, admitted.run_id, context.trace_id ?? "", admitted.executor_generation,
+      principalChain ?? (agent ? [{ kind: "agent", id: agent }] : []), admitted);
+  }
+
+  /** A handle on an existing run at its current generation (no takeover). */
+  async attach(runId, traceId, principalChain) {
+    const status = await this.request("GET", `/v1/runs/${segment(runId)}`);
+    return new Run(this, runId, traceId, status.executor_generation, principalChain, status);
+  }
+
+  /**
+   * Scores a recorded decision as an independent evaluator (a client whose token has
+   * only the `evaluate` scope). The runtime adds the measured cost and latency.
+   */
+  /**
+   * Corrects what a run's principal authorized. Narrowing is open to the executor;
+   * widening needs an `authorize` token that does not run tasks, the principal's
+   * `confirmation_ref` and the same `issued_by`. Resolves to the new revision.
+   */
+  amendTaskAuthorization(runId, expectedRevision, task) {
+    return this.request("PUT", `/v1/runs/${segment(runId)}/task-authorization`, {
+      body: { expected_revision: expectedRevision, task_authorization: task },
+    });
+  }
+
+  score(runId, recordId, { evaluatorRef, policy, utility, safety }) {
+    return this.request("POST", `/v1/runs/${segment(runId)}/decisions/${segment(recordId)}/scores`, {
+      body: { evaluator_ref: evaluatorRef, policy, utility, safety },
+    });
+  }
+
+  /**
+   * Files an operator correction or override against a run as an independent reviewer
+   * (`evaluate` scope); the run's replay case becomes its replay obligation.
+   */
+  fileFeedback(runId, { kind, targetSurface, summary, decisionRecordId, expectedOutcome }) {
+    const body = { kind, target_surface: targetSurface, summary };
+    if (decisionRecordId !== undefined) body.decision_record_id = decisionRecordId;
+    if (expectedOutcome !== undefined) body.expected_outcome = expectedOutcome;
+    return this.request("POST", `/v1/runs/${segment(runId)}/feedback`, { body });
+  }
+
+  /** The tenant's open policy escalations, oldest first (`audit:read`). */
+  openEscalations({ limit = 500 } = {}) {
+    return this.request("GET", "/v1/escalations", { query: { limit } });
+  }
+
+  /**
+   * Records how a human resolved an escalation, `handled` or `dismissed` (`control`).
+   * Grants nothing: an action the human approves is retried through policy.
+   */
+  resolveEscalation(escalationId, resolution, reason) {
+    return this.request("POST", `/v1/escalations/${segment(escalationId)}/resolve`, { body: { resolution, reason } });
+  }
+
+  /** The tenant's open feedback, oldest first: the replay corpus a change must pass. */
+  openFeedback({ limit = 500 } = {}) {
+    return this.request("GET", "/v1/feedback", { query: { limit } });
+  }
+
+  /**
+   * Closes feedback as `fixed`, `still_failing`, `invalid` or `superseded`, with a
+   * reference to the evidence (`control` scope).
+   */
+  closeFeedback(feedbackId, status, { artifactType, artifactId, sha256 }) {
+    return this.request("POST", `/v1/feedback/${segment(feedbackId)}/close`, {
+      body: { status, evidence_ref: { artifact_type: artifactType, artifact_id: artifactId, sha256 } },
+    });
+  }
+
+  /**
+   * Kill switch (token with the `control` scope): revokes a `tenant`, `pack`, `agent`,
+   * `adapter` or `capability` from the next dispatch and admission.
+   */
+  revoke(kind, target, reason) {
+    return this.request("POST", "/v1/revocations", { body: { kind, target, reason } });
+  }
+
+  /** Restores a revoked target. */
+  restore(kind, target, reason) {
+    return this.request("POST", "/v1/revocations/restore", { body: { kind, target, reason } });
+  }
+
+  /** The tenant's revoked targets. */
+  revocations() {
+    return this.request("GET", "/v1/revocations");
+  }
+
+  /** Yields the tenant's signed audit entries in order. */
+  async *auditEntries({ from = 1, page = 500 } = {}) {
+    let cursor = from;
+    while (cursor != null) {
+      const batch = await this.request("GET", "/v1/audit/entries", { query: { from: cursor, limit: page } });
+      yield* batch.entries;
+      cursor = batch.next;
+    }
+  }
+}
+
+export class Run {
+  constructor(client, runId, traceId, executorGeneration, principalChain, admitted = {}) {
+    Object.assign(this, { client, runId, traceId, executorGeneration, principalChain, admitted });
+  }
+
+  #path(suffix = "") {
+    return `/v1/runs/${segment(this.runId)}${suffix}`;
+  }
+
+  #post(suffix, body = {}) {
+    return this.client.request("POST", this.#path(suffix), { body, generation: this.executorGeneration });
+  }
+
+  envelope(capabilityId, args, { approvalMode = "read_only", idempotencyKey = null, evidenceRefs = [], toolCallId } = {}) {
+    return {
+      envelope_version: "contextos.tool_call.v1",
+      tool_call_id: toolCallId ?? `tc_${globalThis.crypto.randomUUID().replaceAll("-", "")}`,
+      run_id: this.runId, trace_id: this.traceId, capability_id: capabilityId, args,
+      principal_chain: this.principalChain, approval_mode_requested: approvalMode,
+      approval_mode_effective: approvalMode, approval_mode_highest: approvalMode,
+      evidence_refs: evidenceRefs, idempotency_key: idempotencyKey,
+    };
+  }
+
+  /** Governs and dispatches one tool call; resolves to its output or throws a ToolOutcome. */
+  async callTool(capabilityId, args, options = {}) {
+    const response = await this.#post("/tool-calls", this.envelope(capabilityId, args, options));
+    // Peer notices that came with this result (peer data, never instructions).
+    this.lastNotices = response.result?.metadata?.notices ?? null;
+    return outcome(response);
+  }
+
+  async provideInput(paused, envelope, responses) {
+    return outcome(await this.#post(`/operations/${segment(paused.operationId ?? "")}/input`,
+      { tool_call: envelope, input_responses: responses }));
+  }
+
+  /** Resolves an unknown effect: by provider query, or by asserting `outcome` with evidence. */
+  reconcile(operationId, { outcome: asserted, evidenceRef } = {}) {
+    const body = asserted === undefined ? { source: "provider" }
+      : { source: "operator", outcome: asserted, evidence_ref: evidenceRef };
+    return this.#post(`/operations/${segment(operationId)}/reconcile`, body);
+  }
+
+  /**
+   * Relays an outcome witness's signed reading (a compact JWS) for an applied effect whose
+   * capability declares an outcome contract. The token needs the `outcome:report` scope.
+   */
+  reportOutcome(operationId, attestation) {
+    return this.client.request("POST", this.#path(`/operations/${segment(operationId)}/outcome`), { body: { attestation } });
+  }
+
+  /** The run's compensable effects and where each stands (`state`). */
+  compensations() {
+    return this.client.request("GET", this.#path("/compensations"));
+  }
+
+  /**
+   * Compensates one applied effect with its declared compensating capability, governed as
+   * a new operation; resolves to its output or throws a ToolOutcome.
+   */
+  async compensate(operationId, { toolCallId } = {}) {
+    const body = { tool_call_id: toolCallId ?? `tc_${globalThis.crypto.randomUUID().replaceAll("-", "")}` };
+    return outcome(await this.#post(`/operations/${segment(operationId)}/compensate`, body));
+  }
+
+  /** Compensates the run's applied effects newest first, stopping at any in doubt. */
+  compensateAll() {
+    return this.#post("/compensate");
+  }
+
+  recordDecision(decisionKey, status, { decisionVersion = "1", toolCalls = [], ...fields } = {}) {
+    return this.#post("/decisions", { decision_key: decisionKey, decision_version: decisionVersion, status,
+      tool_calls: toolCalls, ...fields });
+  }
+
+  /**
+   * Admits a child run in a narrowed lane (AgentDelegationEnvelope). Its budget is
+   * reserved from this run, which must hold the current generation.
+   */
+  async delegate(childAdmission, envelope) {
+    const admitted = await this.client.request("POST", "/v1/runs", {
+      body: { ...childAdmission, delegation: envelope }, generation: this.executorGeneration,
+    });
+    return new Run(this.client, admitted.run_id, childAdmission.run_context?.trace_id ?? this.traceId,
+      admitted.executor_generation, this.principalChain, admitted);
+  }
+
+  /** Closes a delegated child (`accept` or `reject`), settling its spend into this run. */
+  closeChild(child, decision = "accept") {
+    return this.client.request("POST", `/v1/runs/${segment(child.runId)}/close`, {
+      body: { decision }, generation: this.executorGeneration,
+    });
+  }
+
+  /** Saves the orchestrator's state as the next checkpoint revision. */
+  checkpoint(state, expectedRevision) {
+    return this.#post("/checkpoint", { expected_revision: expectedRevision, state });
+  }
+
+  /** The latest checkpoint (`state`, `revision`), e.g. after taking the run over. */
+  latestCheckpoint() {
+    return this.client.request("GET", this.#path("/checkpoint"), { generation: this.executorGeneration });
+  }
+
+  /** Immutable task metadata shared with the root's descendants; grants no tool authority. */
+  publishWork(taskId, title, acceptanceCriteria, { dependencies = [] } = {}) {
+    return this.#post("/work", { task_id: taskId, title, acceptance_criteria: acceptanceCriteria, dependencies });
+  }
+
+  /** A live page; restart at the beginning to discover new earlier ids. */
+  workTasks({ after, limit = 100 } = {}) {
+    return this.client.request("GET", this.#path("/work"), {
+      generation: this.executorGeneration, query: { limit, ...(after === undefined ? {} : { after }) },
+    });
+  }
+
+  workTask(taskId) {
+    return this.client.request("GET", this.#path(`/work/${segment(taskId)}`), { generation: this.executorGeneration });
+  }
+
+  /** Conditional mutation. Inspect after conflicts/lost responses; lease expiry never proves effects safe to repeat. */
+  updateWork(taskId, command) {
+    return this.#post(`/work/${segment(taskId)}`, command);
+  }
+
+  /**
+   * Shares a finding: a claim, or (with `basisOperationId`) an observation bound to a
+   * recorded tool call whose facts the runtime takes from its operation ledger.
+   */
+  publishFinding(findingId, statement, { kind = "claim", dependsOn = [], basisOperationId, basisRunId, refutes, urgent = false } = {}) {
+    const body = { finding_id: findingId, kind, statement, depends_on: dependsOn, urgent };
+    if (refutes !== undefined) body.refutes = refutes;
+    if (basisOperationId !== undefined) {
+      body.kind = "observed";
+      body.basis = { operation_id: basisOperationId, ...(basisRunId === undefined ? {} : { run_id: basisRunId }) };
+    }
+    return this.#post("/findings", body);
+  }
+
+  findings({ after, limit = 100 } = {}) {
+    return this.client.request("GET", this.#path("/findings"), {
+      generation: this.executorGeneration, query: { limit, ...(after === undefined ? {} : { after }) },
+    });
+  }
+
+  /** Falsifies a finding: withdraw your own, or cite an observed finding refuting a peer's. */
+  invalidateFinding(findingId, reason, { refutedBy } = {}) {
+    return this.#post(`/findings/${segment(findingId)}/invalidate`,
+      { reason, ...(refutedBy === undefined ? {} : { refuted_by: refutedBy }) });
+  }
+
+  /** This run's unacknowledged peer notices; reading does not acknowledge them. */
+  notices({ limit = 20 } = {}) {
+    return this.client.request("GET", this.#path("/notices"), { generation: this.executorGeneration, query: { limit } });
+  }
+
+  ackNotices(through) {
+    return this.#post("/notices/ack", { through });
+  }
+
+  /** Reserves budget for a `model_call` or a `replan`; resolves to the reservation id. */
+  async reserveUsage(kind, { tokens = 0, costCents = 0 } = {}) {
+    return (await this.#post("/usage/reserve", { kind, tokens, cost_cents: costCents })).reservation_id;
+  }
+
+  /**
+   * Settles a reservation as the executor: the whole reservation is charged. Pass the
+   * id to your metering gateway instead to settle measured usage.
+   */
+  settleUsage(reservationId) {
+    return this.#post("/usage/settle", { reservation_id: reservationId });
+  }
+
+  /** Headers for a model request that a metering LLM gateway settles with the usage it
+   * measures (`budgetedModelCall(fn, { metered: true })`). */
+  meteringHeaders(reservationId) {
+    return { [RUN_HEADER]: this.runId, [RESERVATION_HEADER]: reservationId };
+  }
+
+  /** Reserves budget for one model call around `fn(reservationId)` and settles it
+   * afterwards, even if `fn` throws. Throws BudgetExhausted before calling `fn` when the
+   * run cannot afford it. `metered: true` leaves settlement to a metering LLM gateway
+   * (send `meteringHeaders(id)`); if `fn` throws, a reservation the gateway did not
+   * settle is settled here, charging all of it. */
+  async budgetedModelCall(fn, { tokens, costCents = 0, metered = false }) {
+    const reservation = await this.reserveUsage("model_call", { tokens, costCents });
+    let result;
+    try {
+      result = await fn(reservation);
+    } catch (error) {
+      await (metered ? this.#settleOpen(reservation) : this.settleUsage(reservation));
+      throw error;
+    }
+    if (!metered) await this.settleUsage(reservation);
+    return result;
+  }
+
+  async #settleOpen(reservationId) {
+    try {
+      await this.settleUsage(reservationId);
+    } catch (error) {
+      if (!(error instanceof ContextOSHTTPError && error.status === 404)) throw error; // settled by the gateway
+    }
+  }
+
+  status() {
+    return this.client.request("GET", this.#path());
+  }
+
+  /** Takes the run over; the previous executor's generation becomes stale. */
+  async takeOver() {
+    const { executor_generation: current } = await this.status();
+    const taken = await this.client.request("POST", this.#path("/takeover"), { body: { expected_generation: current } });
+    this.executorGeneration = taken.executor_generation;
+    return this;
+  }
+
+  complete() { return this.#post("/complete"); }
+  fail() { return this.#post("/fail"); }
+  cancel() { return this.client.request("POST", this.#path("/cancel"), { body: {} }); }
+  evidence() { return this.client.request("GET", this.#path("/evidence")); }
+}
+
+/**
+ * Wraps a capability as an async tool function taking named arguments. Register the
+ * result with any framework that accepts async functions (Vercel AI SDK, LangChain.js,
+ * OpenAI Agents SDK). `idempotencyKey` derives the operation key from the arguments,
+ * and `toolCallId` the call's id, so a DecisionRecord can cite it.
+ */
+export function governedTool(run, capabilityId, { approvalMode = "read_only", idempotencyKey, evidenceRefs = [], toolCallId } = {}) {
+  return (args) => run.callTool(capabilityId, args, {
+    approvalMode, evidenceRefs, idempotencyKey: idempotencyKey ? idempotencyKey(args) : null,
+    toolCallId: toolCallId ? toolCallId(args) : undefined,
+  });
+}
+
+/**
+ * One `AuthorityGrant` scope for a task authorization: this capability, on these
+ * resources, to these destinations, up to `amount` = `[minorUnits, currency]`.
+ */
+export function taskScope(rootRunId, purposeId, capabilityId, {
+  resources = [], destinations = [], classification = "CONFIDENTIAL", amount, argumentConstraints = [],
+} = {}) {
+  const scope = {
+    root_run_id: rootRunId, purpose_ids: [purposeId], capability_ids: [capabilityId],
+    resource_ids: [...resources], destination_ids: [...destinations], classification_labels: [classification],
+    argument_constraints: [...argumentConstraints],
+  };
+  if (amount) scope.amount_ceiling = { minor_units: amount[0], currency: amount[1] };
+  return scope;
+}
+
+/**
+ * What the principal authorized for a run, for `admit(body)` as
+ * `body.task_authorization`. Effects outside every scope are refused
+ * (`outOfScope: "deny"`) or wait for an exact approval (`"ask"`, thrown as
+ * `ToolPaused` with `kind === "approval"`).
+ */
+export function taskAuthorization(issuedBy, scopes, { outOfScope = "deny", readOnly = "allow", confirmationRef, maxEffects, amountTotal } = {}) {
+  const task = { issued_by: issuedBy, scopes, out_of_scope: outOfScope, read_only: readOnly };
+  if (confirmationRef) task.confirmation_ref = confirmationRef;
+  // Bounds on the task as a whole, across all its effects.
+  const limits = {};
+  if (maxEffects !== undefined) limits.max_effects = maxEffects;
+  if (amountTotal) limits.amount_total = { minor_units: amountTotal.minorUnits, currency: amountTotal.currency };
+  if (Object.keys(limits).length) task.limits = limits;
+  return task;
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "contextos-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.12",
+  "description": "HTTP client for contextosd: govern an AI agent's tool calls. No dependencies.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contextosai/ContextOS.git",
+    "directory": "bindings/node"
+  },
+  "homepage": "https://github.com/contextosai/ContextOS/blob/main/bindings/node/README.md",
+  "type": "module",
+  "main": "client.mjs",
+  "types": "client.d.ts",
+  "exports": {
+    ".": {
+      "types": "./client.d.ts",
+      "default": "./client.mjs"
+    }
+  },
+  "files": [
+    "client.mjs",
+    "client.d.ts",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false
+}