contextos-client 0.1.0-alpha.12 → 0.1.0-alpha.14

package/README.md

@@ -27,6 +27,17 @@ Results that are not plain success throw: `ToolPaused` (approval, input, or an u
 outcome to reconcile: never retry blindly), `ToolBlocked`, `ToolRejected`,
 `ToolFailed`. Only requests the server did not process (429, 503) are retried.
 
+`run.checkToolCall(capabilityId, args, options)` answers what `callTool` would do with
+the same call (`allowed`, `approval_required`, `escalation_required`, `blocked` or
+`rejected`, with reason codes and obligations) without effect: nothing is requested,
+reserved or sent, and the check is audited. It is advisory; `not_evaluated` names what
+only dispatch decides.
+
+`client.plan(packRef, runContext, { intent })` (`compile` scope) answers, before any
+request, what a pack lets that principal do: each rule applies `always`, or `when` /
+`unless` a residual condition over `request.*` holds. `client.reloadPacks()` (`control`
+scope) has the server re-read its pack sources and add new versions.
+
 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)

package/client.d.ts

@@ -1,3 +1,18 @@
+/** The answer of `Run.checkToolCall`. */
+export interface ToolCallCheck {
+  status: "allowed" | "approval_required" | "escalation_required" | "blocked" | "rejected";
+  capability_id: Json;
+  operation_id: string | null;
+  action_digest: string | null;
+  reason_codes: string[];
+  obligations: string[];
+  message: string | null;
+  /** The run already has an operation with this id: dispatch treats the call as its retry. */
+  operation_exists: boolean;
+  not_evaluated: ("budget_reservation" | "operation_claim" | "shared_guarantee_capacity")[];
+  audit_sequence: number;
+}
+
 export declare const GENERATION_HEADER: "ContextOS-Executor-Generation";
 
 export type ApprovalMode = "read_only" | "local_write" | "network" | "delegated" | "destructive";
@@ -124,6 +139,35 @@ export interface CallOptions {
   toolCallId?: string;
 }
 
+export interface PlannedRule {
+  bundle_id: string;
+  priority: number;
+  rule_id: string;
+  branch: "then" | "else";
+  effect: "allow" | "require_approval" | "deny";
+  approval_gate?: string;
+  obligations: string[];
+  prohibits: string[];
+  applies: "always" | "when" | "unless";
+  /** Residual JsonLogic over `request.*`, for `when` and `unless`. */
+  condition?: Json;
+}
+
+export interface DecisionPlan {
+  intent: string;
+  verdict: "deny" | "escalate" | "require_approval" | "allow" | "conditional";
+  possible_verdicts: string[] | null;
+  conditions: Json[];
+  rules: PlannedRule[];
+}
+
+export interface PackReload {
+  added: { pack_ref: string; tenant_id: string; sha256: string; path: string }[];
+  refused: { path: string; pack_ref?: string; tenant_id?: string; reason: "invalid" | "pack_ref_immutable" | "tenant_not_configured"; detail: string }[];
+  unchanged: number;
+  other: { added: number; refused: number };
+}
+
 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. */
@@ -149,6 +193,10 @@ export declare class Client {
   revoke(kind: RevocationKind, target: string, reason: string): Promise<Revocations>;
   restore(kind: RevocationKind, target: string, reason: string): Promise<Revocations>;
   revocations(): Promise<Revocations>;
+  /** What a pack lets the run context's principal do for an intent, before any request (`compile`). */
+  plan(packRef: string, runContext: Json, options?: { intent?: string }): Promise<DecisionPlan>;
+  /** Re-reads the server's pack sources and adds new pack versions (`control`). */
+  reloadPacks(): Promise<PackReload>;
   auditEntries(options?: { from?: number; page?: number }): AsyncGenerator<Record<string, Json>>;
 }
 
@@ -197,6 +245,8 @@ export declare class Run {
   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>>;
+  /** What callTool would do with this call, without effect; audited and advisory. */
+  checkToolCall(capabilityId: string, args: Record<string, Json>, options?: CallOptions): Promise<ToolCallCheck>;
   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`. */

package/client.mjs

@@ -18,7 +18,7 @@ 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 CLIENT_VERSION = "0.1.0-alpha.14";
 export const API_VERSION = "v1";
 
 /** The server speaks a different HTTP API generation than this client. */
@@ -270,6 +270,22 @@ export class Client {
     return this.request("GET", "/v1/revocations");
   }
 
+  /**
+   * What `packRef` lets the run context's principal do for an intent before any request
+   * (`compile` scope): each rule applies `always`, or `when` / `unless` a residual
+   * condition over `request.*` holds, with the verdicts those conditions can reach.
+   */
+  async plan(packRef, runContext, { intent } = {}) {
+    const body = { pack_ref: packRef, run_context: runContext };
+    if (intent !== undefined) body.intent = intent;
+    return (await this.request("POST", "/v1/plan", { body })).plan;
+  }
+
+  /** Re-reads the server's pack sources and adds new pack versions (`control` scope). */
+  reloadPacks() {
+    return this.request("POST", "/v1/packs/reload");
+  }
+
   /** Yields the tenant's signed audit entries in order. */
   async *auditEntries({ from = 1, page = 500 } = {}) {
     let cursor = from;
@@ -313,6 +329,16 @@ export class Run {
     return outcome(response);
   }
 
+  /**
+   * What callTool would do with this call, without effect (`status`: allowed,
+   * approval_required, escalation_required, blocked or rejected). Nothing is requested,
+   * reserved or claimed; the check is audited. Advisory: `not_evaluated` names what only
+   * dispatch decides.
+   */
+  async checkToolCall(capabilityId, args, options = {}) {
+    return (await this.#post("/tool-calls/check", this.envelope(capabilityId, args, options))).check;
+  }
+
   async provideInput(paused, envelope, responses) {
     return outcome(await this.#post(`/operations/${segment(paused.operationId ?? "")}/input`,
       { tool_call: envelope, input_responses: responses }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextos-client",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.14",
   "description": "HTTP client for contextosd: govern an AI agent's tool calls. No dependencies.",
   "license": "Apache-2.0",
   "repository": {