@nimble-way/cloudflare-agents 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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 2026 Nimbleway
+
+   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/README.md

@@ -0,0 +1,74 @@
+# Nimble Cloudflare Agents
+
+First-party Cloudflare Agents integration for Nimble Agent API V2. It provides
+a Durable Object-backed agent with resumable create, status, and result tools,
+plus a typed adapter for `@nimble-way/nimble-js`.
+
+## Install
+
+```sh
+npm install @nimble-way/cloudflare-agents agents
+```
+
+## Worker configuration
+
+Export `NimbleRunAgent` from your Worker entry point and bind it as a SQLite
+Durable Object:
+
+```ts
+export { NimbleRunAgent } from "@nimble-way/cloudflare-agents";
+```
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      { "name": "NIMBLE_RUN_AGENT", "class_name": "NimbleRunAgent" }
+    ]
+  },
+  "migrations": [
+    { "tag": "v1", "new_sqlite_classes": ["NimbleRunAgent"] }
+  ]
+}
+```
+
+Set `NIMBLE_API_KEY` as a Worker secret. The agent also accepts an ephemeral
+per-request key override; that value is never persisted in its recovery
+snapshot or run ledger.
+
+If a Worker serves multiple authenticated principals, route each trusted
+principal to a separately named `NimbleRunAgent` instance. Do not multiplex
+untrusted users into one instance: its deterministic create deduplication and
+durable ledger are intentionally scoped to the Durable Object instance. HTTP
+authentication and trusted-principal derivation remain the consuming Worker's
+responsibility.
+
+## Lifecycle guarantees
+
+- Create calls use `maxRetries: 0` to avoid duplicate billable work.
+- A deterministic key deduplicates equivalent create requests.
+- Durable run IDs are recorded before polling begins.
+- Safe status/result reads use bounded retries.
+- Recovery resumes persisted runs and fails closed when an ephemeral key is no
+  longer available.
+- Production polling defaults to 10 seconds and rejects shorter intervals.
+- `startRun()` accepts work asynchronously, so its first response can have a
+  `null` run ID; read lifecycle status to obtain the durable agent/run IDs.
+- Background polling has a five-minute local budget. If the provider run is
+  still active, later status/result reads reconcile it with safe GETs rather
+  than treating the local timeout as a provider failure.
+
+The package owns resumability and Agent API V2 lifecycle behavior. HTTP auth,
+UI/playgrounds, hosted deployments, and AI Gateway transport remain concerns
+of the consuming Worker and are intentionally outside this repository.
+
+## Development
+
+```sh
+npm ci
+npm run check
+```
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,345 @@
+import { Agent, FiberRecoveryContext, FiberRecoveryResult } from 'agents';
+
+/**
+ * Typed Nimble Agent API V2 adapter.
+ *
+ * Create uses @nimble-way/nimble-js 1.2.0's generated types with
+ * maxRetries=0 for BOTH create routes: `client.agents.runs.create(agentId, ...)`
+ * (persistent agent) and `client.agents.run(...)` (agentless, POST
+ * /v2/agents/runs — 1.2.0 exposes this as `AgentRunParams`/`AgentRunResponse`).
+ * Safe status/result GETs retain the bounded adapter-owned backoff policy.
+ */
+declare const NIMBLE_CLIENT_SOURCE = "cloudflare-agents";
+declare const DEFAULT_BASE_URL = "https://sdk.nimbleway.com";
+declare const TERMINAL_STATES: readonly ["completed", "failed", "cancelled"];
+declare const ACTIVE_STATES: readonly ["queued", "running"];
+type TerminalStatus = (typeof TERMINAL_STATES)[number];
+type ActiveStatus = (typeof ACTIVE_STATES)[number];
+/** Statuses this adapter recognizes without inventing semantics for the rest. */
+type KnownRunStatus = ActiveStatus | TerminalStatus;
+type Effort = "low" | "medium" | "high" | "x-high" | "max";
+type SelectableEffort = Effort;
+type UseCase = "research" | "enrichment" | "dataset_building";
+declare const SELECTABLE_EFFORTS: readonly ["low", "medium", "high", "x-high", "max"];
+declare const NIMBLE_ENTERPRISE_CONTACT_URL = "https://www.nimbleway.com/contact";
+declare class GatedFeatureError extends Error {
+    readonly feature = "effort:max";
+    readonly closestAvailable = "x-high";
+    readonly engagementUrl = "https://www.nimbleway.com/contact";
+    constructor();
+}
+interface SourceGroup {
+    title: string;
+    domains: string[];
+    order?: number;
+}
+interface SourceGuidance {
+    allow?: SourceGroup[];
+    block?: SourceGroup[];
+    prioritize?: string | null;
+    avoid?: string | null;
+}
+interface CreateRunRequest {
+    input: string;
+    agent_name?: string | null;
+    effort?: SelectableEffort;
+    input_data?: Record<string, unknown> | Array<Record<string, unknown>>;
+    output_schema?: Record<string, unknown>;
+    previous_interaction_id?: string | null;
+    skill?: string | null;
+    sources?: SourceGuidance | null;
+    use_case?: UseCase | null;
+    enable_events?: boolean;
+}
+interface NimbleRun {
+    id: string;
+    status: string;
+    web_search_agent_id?: string;
+    [key: string]: unknown;
+}
+/**
+ * Types below mirror @nimble-way/nimble-js 1.2.0's actual result envelope
+ * (resources/agents/runs.d.ts RunResultResponse), NOT a guessed flat shape.
+ * A completed run's result is `{ output: { content, trust, type }, run }`;
+ * a failed run's result is `{ error: { message, ref_id }, run }`. There is
+ * no top-level `text`/`json`/`citations`/`trust`/`claims` — those fields,
+ * when present, live under `output` and `output.trust`.
+ */
+interface NimbleTrustCitation {
+    url: string;
+    title?: string | null;
+    excerpts?: string[] | null;
+}
+interface NimbleTrustClaim {
+    confidence: "high" | "medium" | "low" | "pre_existing";
+    reasoning: string;
+    citations: NimbleTrustCitation[];
+    /** Text output: callout marker in the prose. JSON output: JSON path instead. */
+    callout?: number;
+    path?: string;
+}
+interface NimbleTrustSource {
+    type: "primary" | "secondary";
+    url: string;
+    title?: string | null;
+}
+interface NimbleTrust {
+    confidence: "high" | "medium" | "low" | "pre_existing";
+    reasoning: string;
+    claims: NimbleTrustClaim[];
+    sources: NimbleTrustSource[];
+}
+/** Normalized, adapter-facing view of a run's result — never the raw envelope shape. */
+interface NimbleResult {
+    outputType: "text" | "json" | "unknown";
+    /** Prose for text output, structured data for json output. Null for a failed run. */
+    content: string | Record<string, unknown> | unknown[] | null;
+    /** output.trust when the run completed with trust metadata; null for a failed run. */
+    trust: NimbleTrust | null;
+    /** Structured error when the run failed; null for a completed run. */
+    error: {
+        message: string;
+        refId?: string;
+    } | null;
+}
+/**
+ * Normalizes the raw fetched result body into NimbleResult. Handles both
+ * documented envelope shapes (`{output,...}` completed, `{error,...}`
+ * failed) — matches @nimble-way/nimble-js 1.2.0's RunResultResponse exactly,
+ * not a superset guess.
+ */
+declare function normalizeRunResult(raw: unknown): NimbleResult;
+declare class NimbleAgentAPIError extends Error {
+    readonly statusCode: number | undefined;
+    readonly refId: string | undefined;
+    readonly retryAfterSeconds: number | undefined;
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        refId?: string;
+        retryAfterSeconds?: number;
+    });
+}
+/**
+ * A write (create) may or may not have reached Nimble before the transport
+ * failed, or Nimble returned a 5xx that gives no signal either way. Never
+ * retried automatically — the caller must reconcile (list runs for the
+ * agent, or GET the run/agent if an id is already known) before deciding
+ * whether to submit a new create. Do NOT resubmit blindly.
+ */
+declare class AmbiguousCreateError extends NimbleAgentAPIError {
+}
+/** Nimble returned 429 on a create. Never retried per contract. */
+declare class CreateRateLimitedError extends NimbleAgentAPIError {
+}
+declare class PollTimeoutError extends NimbleAgentAPIError {
+}
+interface RetryPolicy {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+}
+declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+interface NimbleClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    retryPolicy?: RetryPolicy;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Adapter for the three Agent API V2 endpoints this starter uses: SDK-backed
+ * typed create, plus adapter-owned status/result GETs.
+ *
+ * Invariant: create is NEVER retried automatically, regardless of status
+ * code (including 429). Safe (GET) reads use bounded backoff honoring
+ * Retry-After.
+ */
+declare class NimbleAgentClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly retryPolicy;
+    private readonly fetchImpl;
+    private readonly sleep;
+    constructor(opts: NimbleClientOptions);
+    private headers;
+    private backoffMs;
+    /**
+     * POST /v2/agents/{agent_id}/runs (persistent agent) or POST
+     * /v2/agents/runs (agentless, server-provisioned agent) — billable,
+     * non-idempotent, NEVER retried. Uses @nimble-way/nimble-js 1.2.0's typed
+     * `client.agents.runs.create` / `client.agents.run` with a client
+     * configured with maxRetries=0.
+     *
+     * A definite 429 fails immediately with CreateRateLimitedError — never
+     * retried. A transport failure or a 5xx (no signal on whether the write
+     * landed) fails with AmbiguousCreateError carrying reconciliation
+     * guidance — never resubmitted automatically by this adapter.
+     */
+    createRun(agentId: string | undefined, body: CreateRunRequest): Promise<NimbleRun>;
+    /** GET /v2/agents/{agent_id}/runs/{run_id} — safe to retry with backoff. */
+    getRunStatus(agentId: string, runId: string): Promise<NimbleRun>;
+    /**
+     * GET /v2/agents/{agent_id}/runs/{run_id}/result — safe to retry with
+     * backoff. Normalizes the raw envelope (`{output,...}` / `{error,...}`)
+     * into NimbleResult so every caller (agent.ts, the UI) sees a faithful,
+     * generic shape instead of guessing at top-level fields.
+     */
+    getRunResult(agentId: string, runId: string): Promise<NimbleResult>;
+    private safeGet;
+}
+/** Fails closed on any status this adapter does not recognize (no invented semantics). */
+declare function classifyStatus(status: string): "active" | "terminal" | "unknown";
+
+interface Env {
+    NIMBLE_RUN_AGENT: DurableObjectNamespace<NimbleRunAgent>;
+    /** Protected server-secret fallback; overridden per-request by an ephemeral user key. */
+    NIMBLE_API_KEY?: string;
+    NIMBLE_BASE_URL?: string;
+    /** Backend Agent API V2 status interval. Defaults to 10s; production values must be >=10s. */
+    NIMBLE_POLL_INTERVAL_MS?: string;
+    /** Test-only escape hatch for zero/short polling intervals. Never set in production. */
+    NIMBLE_TEST_ALLOW_SHORT_POLL_INTERVALS?: string;
+}
+interface RunLedgerRow {
+    agentId: string;
+    runId: string | null;
+    status: string;
+    createdAt: number;
+    updatedAt: number;
+    pollAttempts: number;
+    fiberIdempotencyKey: string;
+    recoveredCount: number;
+    lastError: string | null;
+    /** True if this run was created/polled using an ephemeral per-user key override. */
+    usedOverrideKey: boolean;
+}
+interface AgentState {
+    runs: Record<string, RunLedgerRow>;
+}
+interface StartRunInput {
+    /** Omit to use POST /v2/agents/runs and let Nimble provision the WSA. */
+    nimbleAgentId?: string;
+    request: CreateRunRequest;
+    /** Ephemeral per-user API key override; falls back to env.NIMBLE_API_KEY. */
+    apiKeyOverride?: string;
+}
+interface StartRunOutcome {
+    fiberKey: string;
+    accepted: boolean;
+    runId: string | null;
+    status: string;
+}
+interface StatusOutcome {
+    fiberKey: string;
+    runId: string | null;
+    /** Nimble's durable web_search_agent_id (wsa_...), distinct from runId (task_run_...). */
+    agentId: string | null;
+    status: string;
+    pollAttempts: number;
+    recoveredCount: number;
+    lastError: string | null;
+}
+interface ResultOutcome {
+    fiberKey: string;
+    runId: string | null;
+    /** Nimble's durable web_search_agent_id (wsa_...), distinct from runId (task_run_...). */
+    agentId: string | null;
+    status: string;
+    result: NimbleResult | null;
+    error: string | null;
+}
+declare const DEFAULT_POLL_INTERVAL_MS = 10000;
+declare function resolvePollIntervalMs(env: Pick<Env, "NIMBLE_POLL_INTERVAL_MS" | "NIMBLE_TEST_ALLOW_SHORT_POLL_INTERVALS">): number;
+/**
+ * Deterministic idempotency key: the SAME full create request (every field
+ * that affects what Nimble is billed to do — input, agent_name, effort,
+ * enable_events, input_data, output_schema, previous_interaction_id, skill,
+ * sources, and use_case) never issues a second create.
+ *
+ * Design notes:
+ * - Covers the FULL request, not a subset. Two requests differing only in
+ *   `effort` or `enable_events` are billed differently by Nimble and must
+ *   dedupe to DIFFERENT keys, not collapse into "same run".
+ * - Uses SHA-256 (Web Crypto, available in workerd) over a canonical JSON
+ *   encoding, not a 32-bit rolling hash — a 32-bit hash has a ~50% collision
+ *   chance past ~77k distinct requests (birthday bound) sharing one Durable
+ *   Object's ledger, which is within reach for a long-lived agent session
+ *   and would silently merge two unrelated runs into one idempotency key.
+ *   SHA-256's 256-bit space makes accidental collision practically zero.
+ * - Deliberately excludes `apiKeyOverride`: the idempotency key identifies
+ *   "what work", not "which credential authorized it" — the same task run
+ *   twice with two different per-user keys should still dedupe (whoever
+ *   asked first wins the create; see "Recovery for override-backed runs"
+ *   for how the credential itself is handled separately and never persisted).
+ */
+declare function deriveFiberKey(nimbleAgentId: string | undefined, request: CreateRunRequest): Promise<string>;
+/**
+ * Durable Object-backed Agent owning one Nimble Agent API V2 run lifecycle
+ * per fiber key. Uses agents@0.20.0's startFiber() for durable acceptance,
+ * dedupe, and crash recovery.
+ */
+declare class NimbleRunAgent extends Agent<Env, AgentState> {
+    initialState: AgentState;
+    private client;
+    private upsertLedger;
+    /**
+     * "start" tool. Never retries the create; deduplicates via startFiber's
+     * idempotencyKey so a duplicate call with the same (agent_id, input) joins
+     * the existing run instead of billing a second create.
+     */
+    startRun(input: StartRunInput): Promise<StartRunOutcome>;
+    private pollUntilTerminal;
+    /**
+     * Self-healing reconciliation for a non-terminal ledger row. The
+     * background fiber's own poll loop (pollUntilTerminal) waits on a plain
+     * `await new Promise(setTimeout(...))`, which does NOT survive a Durable
+     * Object eviction/hibernation — unlike a DO alarm, nothing wakes the
+     * isolate to resolve that timer, so if the fiber is evicted while
+     * suspended there, the whole callback is gone and onFiberRecovered's
+     * automatic resume is the only thing that can restart it. If that SDK
+     * hook does not fire (or fires without effect) for some reason, the
+     * ledger is otherwise stuck forever with a valid runId and no way
+     * forward. This is a general, run-agnostic repair: any time a caller
+     * reads status/result for a row that looks stale, do ONE safe GET
+     * ourselves to bring the ledger current — never a create, and only ever
+     * a GET the caller is already authorized to make.
+     *
+     * Skips (leaves the ledger untouched) when: there is no runId yet, the
+     * row is already terminal, the row is "recovery-blocked" (that state
+     * requires the explicit resumeWithOverride() flow, not a background
+     * reconcile), the row needs an override the caller did not supply, or
+     * less than one poll interval has passed since the last update (avoids
+     * turning every status read into an extra live GET for a row that is
+     * still being actively polled by a healthy fiber).
+     */
+    private reconcileIfStale;
+    /**
+     * Called automatically by the SDK on the next activation if this Agent
+     * was evicted mid-fiber. Resumes polling from the stashed run id — never
+     * re-issues a create.
+     */
+    onFiberRecovered(ctx: FiberRecoveryContext): Promise<void | FiberRecoveryResult>;
+    /**
+     * "status" tool. `apiKeyOverride` is optional and only used to reconcile
+     * an override-backed row that has gone stale (see reconcileIfStale) — it
+     * is never required just to read the ledger's last-known state.
+     */
+    getRunLifecycleStatus(fiberKey: string, apiKeyOverride?: string): Promise<StatusOutcome>;
+    /**
+     * Explicit operator recovery for an already-created run. Performs one
+     * safe provider GET regardless of the ordinary poll throttle, then returns
+     * the durable ledger state. This can never issue a create.
+     */
+    reconcileRunLifecycleStatus(fiberKey: string, apiKeyOverride?: string): Promise<StatusOutcome>;
+    /** "result" tool. Fetches the typed Nimble result once the run is terminal. */
+    getRunTypedResult(fiberKey: string, apiKeyOverride?: string): Promise<ResultOutcome>;
+    /**
+     * Resumes a "recovery-blocked" override-backed run once the caller
+     * re-supplies the same (or an equivalently authorized) API key. Never
+     * used to retry the create — only to resume polling an already-created
+     * run. See onFiberRecovered's fail-closed handling above.
+     */
+    resumeWithOverride(fiberKey: string, apiKeyOverride: string): Promise<StatusOutcome>;
+}
+
+export { ACTIVE_STATES, type ActiveStatus, type AgentState, AmbiguousCreateError, CreateRateLimitedError, type CreateRunRequest, DEFAULT_BASE_URL, DEFAULT_POLL_INTERVAL_MS, DEFAULT_RETRY_POLICY, type Effort, type Env, GatedFeatureError, type KnownRunStatus, NIMBLE_CLIENT_SOURCE, NIMBLE_ENTERPRISE_CONTACT_URL, NimbleAgentAPIError, NimbleAgentClient, type NimbleClientOptions, type NimbleResult, type NimbleRun, NimbleRunAgent, type NimbleTrust, type NimbleTrustCitation, type NimbleTrustClaim, type NimbleTrustSource, PollTimeoutError, type ResultOutcome, type RetryPolicy, type RunLedgerRow, SELECTABLE_EFFORTS, type SelectableEffort, type SourceGroup, type SourceGuidance, type StartRunInput, type StartRunOutcome, type StatusOutcome, TERMINAL_STATES, type TerminalStatus, type UseCase, classifyStatus, deriveFiberKey, normalizeRunResult, resolvePollIntervalMs };

package/dist/index.js

@@ -0,0 +1,698 @@
+// src/agent.ts
+import { Agent } from "agents";
+
+// src/nimble-client.ts
+import Nimble, { APIConnectionError, APIError } from "@nimble-way/nimble-js";
+var NIMBLE_CLIENT_SOURCE = "cloudflare-agents";
+var DEFAULT_BASE_URL = "https://sdk.nimbleway.com";
+var TERMINAL_STATES = ["completed", "failed", "cancelled"];
+var ACTIVE_STATES = ["queued", "running"];
+var SELECTABLE_EFFORTS = ["low", "medium", "high", "x-high", "max"];
+var NIMBLE_ENTERPRISE_CONTACT_URL = "https://www.nimbleway.com/contact";
+var GatedFeatureError = class extends Error {
+  feature = "effort:max";
+  closestAvailable = "x-high";
+  engagementUrl = NIMBLE_ENTERPRISE_CONTACT_URL;
+  constructor() {
+    super(
+      `Nimble Max effort is a coming-soon custom-budget feature. Contact Nimble to enable it: ${NIMBLE_ENTERPRISE_CONTACT_URL}. To continue now, explicitly select x-high; this integration never silently substitutes it.`
+    );
+    this.name = "GatedFeatureError";
+  }
+};
+function normalizeRunResult(raw) {
+  const body = raw && typeof raw === "object" ? raw : {};
+  const output = body.output;
+  if (output && typeof output === "object") {
+    const outputBody = output;
+    const trustRaw = outputBody.trust;
+    const trust = trustRaw && typeof trustRaw === "object" ? trustRaw : null;
+    const outputType = outputBody.type === "json" ? "json" : outputBody.type === "text" ? "text" : "unknown";
+    return {
+      outputType,
+      content: outputBody.content ?? null,
+      trust,
+      error: null
+    };
+  }
+  const errorRaw = body.error;
+  if (errorRaw && typeof errorRaw === "object") {
+    const errorBody = errorRaw;
+    if (typeof errorBody.message === "string") {
+      return {
+        outputType: "unknown",
+        content: null,
+        trust: null,
+        error: {
+          message: errorBody.message,
+          refId: typeof errorBody.ref_id === "string" ? errorBody.ref_id : void 0
+        }
+      };
+    }
+  }
+  return { outputType: "unknown", content: null, trust: null, error: null };
+}
+var NimbleAgentAPIError = class extends Error {
+  statusCode;
+  refId;
+  retryAfterSeconds;
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "NimbleAgentAPIError";
+    this.statusCode = opts.statusCode;
+    this.refId = opts.refId;
+    this.retryAfterSeconds = opts.retryAfterSeconds;
+  }
+};
+var AmbiguousCreateError = class extends NimbleAgentAPIError {
+};
+var AMBIGUOUS_RECONCILIATION_GUIDANCE = "Do not resubmit automatically. Reconcile first: list runs for the agent (or GET the run/agent by id if you already captured one) to check whether the earlier create actually landed, then decide whether a new create is needed.";
+var CreateRateLimitedError = class extends NimbleAgentAPIError {
+};
+var PollTimeoutError = class extends NimbleAgentAPIError {
+};
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 8e3
+};
+var AGENT_ID_RE = /^wsa_[A-Za-z0-9_-]+$/;
+var RUN_ID_RE = /^task_run_[A-Za-z0-9_-]+$/;
+function requireId(value, pattern, label) {
+  if (!pattern.test(value)) {
+    throw new Error(`${label} has an unexpected format`);
+  }
+  return value;
+}
+function parseRetryAfter(headers) {
+  const value = headers.get("Retry-After");
+  if (!value) return void 0;
+  const asNumber = Number(value);
+  if (Number.isFinite(asNumber)) return Math.max(0, asNumber);
+  const asDate = Date.parse(value);
+  if (Number.isNaN(asDate)) return void 0;
+  return Math.max(0, (asDate - Date.now()) / 1e3);
+}
+async function safeErrorFromResponse(response) {
+  let message = `Nimble request failed with HTTP ${response.status}`;
+  let refId;
+  try {
+    const body = await response.clone().json();
+    const candidate = body?.message ?? body?.detail ?? body?.msg;
+    if (typeof candidate === "string" && candidate.trim()) {
+      message = candidate.trim().slice(0, 500);
+    } else if (candidate && typeof candidate === "object") {
+      const nested = candidate;
+      const nestedMessage = nested.message ?? nested.detail ?? nested.msg;
+      if (typeof nestedMessage === "string" && nestedMessage.trim()) {
+        message = nestedMessage.trim().slice(0, 500);
+      }
+    }
+    const candidateRef = body?.ref_id ?? body?.task_id;
+    if (typeof candidateRef === "string") refId = candidateRef.slice(0, 200);
+  } catch {
+  }
+  return new NimbleAgentAPIError(message, {
+    statusCode: response.status,
+    refId,
+    retryAfterSeconds: parseRetryAfter(response.headers)
+  });
+}
+function sdkErrorMessage(error) {
+  const body = error.error;
+  const candidate = body?.message ?? body?.detail ?? body?.msg;
+  if (typeof candidate === "string" && candidate.trim()) {
+    return candidate.trim().slice(0, 500);
+  }
+  if (Array.isArray(candidate)) {
+    const issues = candidate.slice(0, 3).map((issue) => {
+      if (!issue || typeof issue !== "object") return null;
+      const entry = issue;
+      const location = Array.isArray(entry.loc) ? entry.loc.filter((part) => typeof part === "string" || typeof part === "number").join(".") : "request";
+      const message = typeof entry.msg === "string" ? entry.msg : "validation failed";
+      return `${location || "request"}: ${message}`;
+    }).filter((issue) => Boolean(issue));
+    if (issues.length) return issues.join("; ").slice(0, 500);
+  } else if (candidate && typeof candidate === "object") {
+    const nested = candidate;
+    const nestedMessage = nested.message ?? nested.detail ?? nested.msg;
+    if (typeof nestedMessage === "string" && nestedMessage.trim()) {
+      return nestedMessage.trim().slice(0, 500);
+    }
+  }
+  return `Nimble request failed with HTTP ${error.status ?? "unknown"}`;
+}
+function sdkErrorRefId(error) {
+  const body = error.error;
+  const candidate = body?.ref_id ?? body?.task_id;
+  return typeof candidate === "string" ? candidate.slice(0, 200) : void 0;
+}
+var NimbleAgentClient = class {
+  apiKey;
+  baseUrl;
+  retryPolicy;
+  fetchImpl;
+  sleep;
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("apiKey is required");
+    this.apiKey = opts.apiKey;
+    this.baseUrl = opts.baseUrl ?? DEFAULT_BASE_URL;
+    this.retryPolicy = opts.retryPolicy ?? DEFAULT_RETRY_POLICY;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    this.fetchImpl = (input, init) => fetchImpl(input, init);
+    this.sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  }
+  headers() {
+    return {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      "X-Client-Source": NIMBLE_CLIENT_SOURCE
+    };
+  }
+  backoffMs(attempt, retryAfterSeconds) {
+    if (retryAfterSeconds !== void 0) {
+      return Math.min(retryAfterSeconds * 1e3, this.retryPolicy.maxDelayMs);
+    }
+    const exponential = this.retryPolicy.baseDelayMs * 2 ** (attempt - 1);
+    return Math.min(exponential, this.retryPolicy.maxDelayMs);
+  }
+  /**
+   * POST /v2/agents/{agent_id}/runs (persistent agent) or POST
+   * /v2/agents/runs (agentless, server-provisioned agent) — billable,
+   * non-idempotent, NEVER retried. Uses @nimble-way/nimble-js 1.2.0's typed
+   * `client.agents.runs.create` / `client.agents.run` with a client
+   * configured with maxRetries=0.
+   *
+   * A definite 429 fails immediately with CreateRateLimitedError — never
+   * retried. A transport failure or a 5xx (no signal on whether the write
+   * landed) fails with AmbiguousCreateError carrying reconciliation
+   * guidance — never resubmitted automatically by this adapter.
+   */
+  async createRun(agentId, body) {
+    if (agentId) requireId(agentId, AGENT_ID_RE, "agent_id");
+    if (!body.input?.trim()) throw new Error("input is required");
+    const requestedEffort = body.effort;
+    if (requestedEffort === "max") {
+      throw new GatedFeatureError();
+    }
+    if (requestedEffort !== void 0 && !(typeof requestedEffort === "string" && SELECTABLE_EFFORTS.includes(requestedEffort))) {
+      throw new Error("effort must be one of: low, medium, high, x-high, max");
+    }
+    const client = new Nimble({
+      apiKey: this.apiKey,
+      baseURL: this.baseUrl,
+      clientSource: NIMBLE_CLIENT_SOURCE,
+      fetch: this.fetchImpl,
+      maxRetries: 0
+    });
+    let run;
+    try {
+      if (agentId) {
+        run = await client.agents.runs.create(agentId, {
+          enable_events: false,
+          ...body
+        });
+      } else {
+        run = await client.agents.run({
+          enable_events: false,
+          ...body
+        });
+      }
+    } catch (err) {
+      if (err instanceof NimbleAgentAPIError || err instanceof Error && err.name === "NimbleAgentAPIError" && "statusCode" in err) {
+        throw err;
+      }
+      if (err instanceof APIConnectionError) {
+        throw new AmbiguousCreateError(
+          `Nimble create-run outcome is unknown after a transport failure. ${AMBIGUOUS_RECONCILIATION_GUIDANCE}`,
+          {}
+        );
+      }
+      if (err instanceof APIError) {
+        const statusCode = err.status;
+        const message = sdkErrorMessage(err);
+        const refId = sdkErrorRefId(err);
+        const retryAfterSeconds = err.headers ? parseRetryAfter(err.headers) : void 0;
+        if (statusCode === 429) {
+          throw new CreateRateLimitedError(message, {
+            statusCode,
+            refId,
+            retryAfterSeconds
+          });
+        }
+        if (statusCode !== void 0 && statusCode >= 500) {
+          throw new AmbiguousCreateError(
+            `Nimble create-run returned HTTP ${statusCode} (${message}); outcome is unknown. ${AMBIGUOUS_RECONCILIATION_GUIDANCE}`,
+            { statusCode, refId, retryAfterSeconds }
+          );
+        }
+        throw new NimbleAgentAPIError(message, {
+          statusCode,
+          refId,
+          retryAfterSeconds
+        });
+      }
+      throw new AmbiguousCreateError(
+        `Nimble create-run outcome is unknown after a transport failure. ${AMBIGUOUS_RECONCILIATION_GUIDANCE}`,
+        {}
+      );
+    }
+    requireId(String(run.id ?? ""), RUN_ID_RE, "created run id");
+    const resolvedAgentId = requireId(
+      String(run.web_search_agent_id ?? agentId ?? ""),
+      AGENT_ID_RE,
+      "created agent id"
+    );
+    if (agentId && resolvedAgentId !== agentId) {
+      throw new NimbleAgentAPIError(
+        `Nimble create-run returned web_search_agent_id ${resolvedAgentId}, which does not match the requested agent_id ${agentId}`
+      );
+    }
+    return { ...run };
+  }
+  /** GET /v2/agents/{agent_id}/runs/{run_id} — safe to retry with backoff. */
+  async getRunStatus(agentId, runId) {
+    requireId(agentId, AGENT_ID_RE, "agent_id");
+    requireId(runId, RUN_ID_RE, "run_id");
+    return this.safeGet(`${this.baseUrl}/v2/agents/${agentId}/runs/${runId}`);
+  }
+  /**
+   * GET /v2/agents/{agent_id}/runs/{run_id}/result — safe to retry with
+   * backoff. Normalizes the raw envelope (`{output,...}` / `{error,...}`)
+   * into NimbleResult so every caller (agent.ts, the UI) sees a faithful,
+   * generic shape instead of guessing at top-level fields.
+   */
+  async getRunResult(agentId, runId) {
+    requireId(agentId, AGENT_ID_RE, "agent_id");
+    requireId(runId, RUN_ID_RE, "run_id");
+    const raw = await this.safeGet(`${this.baseUrl}/v2/agents/${agentId}/runs/${runId}/result`);
+    return normalizeRunResult(raw);
+  }
+  async safeGet(url) {
+    let lastError;
+    for (let attempt = 1; attempt <= this.retryPolicy.maxAttempts; attempt++) {
+      let response;
+      try {
+        response = await this.fetchImpl(url, { method: "GET", headers: this.headers() });
+      } catch {
+        if (attempt === this.retryPolicy.maxAttempts) {
+          throw new NimbleAgentAPIError("Nimble request failed after safe retries");
+        }
+        await this.sleep(this.backoffMs(attempt, void 0));
+        continue;
+      }
+      if (response.ok) {
+        return await response.json();
+      }
+      const retryable = response.status === 408 || response.status === 429 || response.status >= 500;
+      if (retryable && attempt < this.retryPolicy.maxAttempts) {
+        lastError = await safeErrorFromResponse(response);
+        await this.sleep(this.backoffMs(attempt, lastError.retryAfterSeconds));
+        continue;
+      }
+      throw await safeErrorFromResponse(response);
+    }
+    throw lastError ?? new NimbleAgentAPIError("Nimble request failed after safe retries");
+  }
+};
+function classifyStatus(status) {
+  if (ACTIVE_STATES.includes(status)) return "active";
+  if (TERMINAL_STATES.includes(status)) return "terminal";
+  return "unknown";
+}
+
+// src/agent.ts
+var DEFAULT_POLL_INTERVAL_MS = 1e4;
+var POLL_DEADLINE_MS = 5 * 6e4;
+function resolvePollIntervalMs(env) {
+  const raw = env.NIMBLE_POLL_INTERVAL_MS;
+  if (raw === void 0 || raw === "") return DEFAULT_POLL_INTERVAL_MS;
+  const intervalMs = Number(raw);
+  if (!Number.isSafeInteger(intervalMs) || intervalMs < 0) {
+    throw new Error("NIMBLE_POLL_INTERVAL_MS must be a non-negative integer");
+  }
+  if (intervalMs < DEFAULT_POLL_INTERVAL_MS && env.NIMBLE_TEST_ALLOW_SHORT_POLL_INTERVALS !== "true") {
+    throw new Error(
+      "NIMBLE_POLL_INTERVAL_MS values below 10000 are test-only; set NIMBLE_TEST_ALLOW_SHORT_POLL_INTERVALS=true only in tests"
+    );
+  }
+  return intervalMs;
+}
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, nested]) => [key, canonicalize(nested)])
+    );
+  }
+  return value;
+}
+async function deriveFiberKey(nimbleAgentId, request) {
+  const canonical = JSON.stringify(
+    canonicalize({
+      agent_id: nimbleAgentId ?? null,
+      input: request.input,
+      agent_name: request.agent_name ?? null,
+      effort: request.effort ?? null,
+      enable_events: request.enable_events ?? false,
+      input_data: request.input_data ?? null,
+      output_schema: request.output_schema ?? null,
+      previous_interaction_id: request.previous_interaction_id ?? null,
+      skill: request.skill ?? null,
+      sources: request.sources ?? null,
+      use_case: request.use_case ?? null
+    })
+  );
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+  const hex = Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `nimble-run:${nimbleAgentId ?? "generated"}:${hex}`;
+}
+var NimbleRunAgent = class extends Agent {
+  initialState = { runs: {} };
+  client(apiKeyOverride) {
+    const apiKey = apiKeyOverride || this.env.NIMBLE_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "No Nimble API key available: no per-user override and NIMBLE_API_KEY is unset"
+      );
+    }
+    return new NimbleAgentClient({
+      apiKey,
+      baseUrl: this.env.NIMBLE_BASE_URL
+    });
+  }
+  upsertLedger(fiberKey, patch) {
+    const now = Date.now();
+    const existing = this.state.runs[fiberKey];
+    const row = {
+      agentId: existing?.agentId ?? "",
+      runId: existing?.runId ?? null,
+      status: existing?.status ?? "queued",
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now,
+      pollAttempts: existing?.pollAttempts ?? 0,
+      fiberIdempotencyKey: fiberKey,
+      recoveredCount: existing?.recoveredCount ?? 0,
+      lastError: existing?.lastError ?? null,
+      usedOverrideKey: existing?.usedOverrideKey ?? false,
+      ...patch
+    };
+    this.setState({ runs: { ...this.state.runs, [fiberKey]: row } });
+  }
+  /**
+   * "start" tool. Never retries the create; deduplicates via startFiber's
+   * idempotencyKey so a duplicate call with the same (agent_id, input) joins
+   * the existing run instead of billing a second create.
+   */
+  async startRun(input) {
+    const fiberKey = await deriveFiberKey(input.nimbleAgentId, input.request);
+    const usedOverrideKey = Boolean(input.apiKeyOverride);
+    if (!this.state.runs[fiberKey]) {
+      this.upsertLedger(fiberKey, {
+        agentId: input.nimbleAgentId ?? "",
+        status: "queued",
+        usedOverrideKey
+      });
+    }
+    const receipt = await this.startFiber(
+      fiberKey,
+      async (ctx) => {
+        let run;
+        try {
+          const client = this.client(input.apiKeyOverride);
+          run = await client.createRun(input.nimbleAgentId, input.request);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          this.upsertLedger(fiberKey, { status: "failed", lastError: message });
+          throw err;
+        }
+        const resolvedAgentId = String(run.web_search_agent_id ?? input.nimbleAgentId ?? "");
+        const snapshot = {
+          nimbleAgentId: resolvedAgentId,
+          runId: run.id,
+          usedOverrideKey
+        };
+        ctx.stash(snapshot);
+        this.upsertLedger(fiberKey, {
+          agentId: resolvedAgentId,
+          runId: run.id,
+          status: run.status
+        });
+        await this.pollUntilTerminal(fiberKey, resolvedAgentId, run.id, ctx.signal, input.apiKeyOverride);
+      },
+      { idempotencyKey: fiberKey, metadata: { nimbleAgentId: input.nimbleAgentId ?? "generated" } }
+    );
+    const row = this.state.runs[fiberKey];
+    return {
+      fiberKey,
+      accepted: receipt.accepted,
+      runId: row?.runId ?? null,
+      status: row?.status ?? "queued"
+    };
+  }
+  async pollUntilTerminal(fiberKey, nimbleAgentId, runId, signal, apiKeyOverride) {
+    const client = this.client(apiKeyOverride);
+    const deadline = Date.now() + POLL_DEADLINE_MS;
+    const pollIntervalMs = resolvePollIntervalMs(this.env);
+    while (!signal.aborted) {
+      const run = await client.getRunStatus(nimbleAgentId, runId);
+      const status = String(run.status);
+      const kind = classifyStatus(status);
+      const attempts = (this.state.runs[fiberKey]?.pollAttempts ?? 0) + 1;
+      this.upsertLedger(fiberKey, { status, pollAttempts: attempts, lastError: null });
+      if (kind === "terminal") return;
+      if (kind === "unknown") {
+        this.upsertLedger(fiberKey, { status: "failed", lastError: `Unknown run status: ${status}` });
+        throw new NimbleAgentAPIError(`Unknown run status: ${status}`, { refId: runId });
+      }
+      if (Date.now() > deadline) {
+        this.upsertLedger(fiberKey, { lastError: "Polling deadline exceeded" });
+        throw new PollTimeoutError("Timed out waiting for a terminal Nimble run status", {
+          refId: runId
+        });
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+  }
+  /**
+   * Self-healing reconciliation for a non-terminal ledger row. The
+   * background fiber's own poll loop (pollUntilTerminal) waits on a plain
+   * `await new Promise(setTimeout(...))`, which does NOT survive a Durable
+   * Object eviction/hibernation — unlike a DO alarm, nothing wakes the
+   * isolate to resolve that timer, so if the fiber is evicted while
+   * suspended there, the whole callback is gone and onFiberRecovered's
+   * automatic resume is the only thing that can restart it. If that SDK
+   * hook does not fire (or fires without effect) for some reason, the
+   * ledger is otherwise stuck forever with a valid runId and no way
+   * forward. This is a general, run-agnostic repair: any time a caller
+   * reads status/result for a row that looks stale, do ONE safe GET
+   * ourselves to bring the ledger current — never a create, and only ever
+   * a GET the caller is already authorized to make.
+   *
+   * Skips (leaves the ledger untouched) when: there is no runId yet, the
+   * row is already terminal, the row is "recovery-blocked" (that state
+   * requires the explicit resumeWithOverride() flow, not a background
+   * reconcile), the row needs an override the caller did not supply, or
+   * less than one poll interval has passed since the last update (avoids
+   * turning every status read into an extra live GET for a row that is
+   * still being actively polled by a healthy fiber).
+   */
+  async reconcileIfStale(fiberKey, apiKeyOverride, forceSafeRead = false) {
+    const row = this.state.runs[fiberKey];
+    if (!row?.runId) return;
+    if (classifyStatus(row.status) === "terminal") return;
+    if (row.status === "recovery-blocked") return;
+    if (row.usedOverrideKey && !apiKeyOverride) return;
+    const pollIntervalMs = resolvePollIntervalMs(this.env);
+    if (!forceSafeRead && Date.now() - row.updatedAt < pollIntervalMs) return;
+    try {
+      const client = this.client(apiKeyOverride);
+      const run = await client.getRunStatus(row.agentId, row.runId);
+      const status = String(run.status);
+      const kind = classifyStatus(status);
+      const attempts = (this.state.runs[fiberKey]?.pollAttempts ?? 0) + 1;
+      if (kind === "unknown") {
+        this.upsertLedger(fiberKey, {
+          status: "failed",
+          pollAttempts: attempts,
+          lastError: `Unknown run status: ${status}`
+        });
+        return;
+      }
+      this.upsertLedger(fiberKey, { status, pollAttempts: attempts, lastError: null });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.upsertLedger(fiberKey, { lastError: message });
+    }
+  }
+  /**
+   * Called automatically by the SDK on the next activation if this Agent
+   * was evicted mid-fiber. Resumes polling from the stashed run id — never
+   * re-issues a create.
+   */
+  async onFiberRecovered(ctx) {
+    const snapshot = ctx.snapshot;
+    const fiberKey = ctx.idempotencyKey ?? ctx.name;
+    this.upsertLedger(fiberKey, {
+      recoveredCount: (this.state.runs[fiberKey]?.recoveredCount ?? 0) + 1
+    });
+    if (!snapshot?.runId) {
+      this.upsertLedger(fiberKey, {
+        status: "failed",
+        lastError: "Recovered before create was confirmed; not retried (ambiguous write)"
+      });
+      return { status: "error", error: "create-outcome-unknown-not-retried" };
+    }
+    if (snapshot.usedOverrideKey) {
+      this.upsertLedger(fiberKey, {
+        status: "recovery-blocked",
+        lastError: "Recovery blocked: this run was authorized with a per-user API key override that is never persisted and cannot be safely re-supplied automatically. The server fallback key was deliberately NOT used to avoid a cross-account credential switch. Re-supply the same override via the result/status tool to continue."
+      });
+      return {
+        status: "error",
+        error: "override-key-recovery-blocked-fail-closed",
+        snapshot
+      };
+    }
+    try {
+      const controller = new AbortController();
+      await this.pollUntilTerminal(
+        fiberKey,
+        snapshot.nimbleAgentId,
+        snapshot.runId,
+        controller.signal
+      );
+      return { status: "completed", snapshot };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { status: "error", error: message, snapshot };
+    }
+  }
+  /**
+   * "status" tool. `apiKeyOverride` is optional and only used to reconcile
+   * an override-backed row that has gone stale (see reconcileIfStale) — it
+   * is never required just to read the ledger's last-known state.
+   */
+  async getRunLifecycleStatus(fiberKey, apiKeyOverride) {
+    await this.reconcileIfStale(fiberKey, apiKeyOverride);
+    const inspected = await this.inspectFiberByKey(fiberKey);
+    const row = this.state.runs[fiberKey];
+    return {
+      fiberKey,
+      runId: row?.runId ?? null,
+      agentId: row?.agentId || null,
+      status: row?.status ?? inspected?.status ?? "unknown",
+      pollAttempts: row?.pollAttempts ?? 0,
+      recoveredCount: row?.recoveredCount ?? 0,
+      lastError: row?.lastError ?? null
+    };
+  }
+  /**
+   * Explicit operator recovery for an already-created run. Performs one
+   * safe provider GET regardless of the ordinary poll throttle, then returns
+   * the durable ledger state. This can never issue a create.
+   */
+  async reconcileRunLifecycleStatus(fiberKey, apiKeyOverride) {
+    await this.reconcileIfStale(fiberKey, apiKeyOverride, true);
+    return this.getRunLifecycleStatus(fiberKey, apiKeyOverride);
+  }
+  /** "result" tool. Fetches the typed Nimble result once the run is terminal. */
+  async getRunTypedResult(fiberKey, apiKeyOverride) {
+    await this.reconcileIfStale(fiberKey, apiKeyOverride);
+    const row = this.state.runs[fiberKey];
+    if (!row?.runId) {
+      return {
+        fiberKey,
+        runId: null,
+        agentId: row?.agentId || null,
+        status: row?.status ?? "unknown",
+        result: null,
+        error: row?.lastError ?? "no run id yet"
+      };
+    }
+    if (row.usedOverrideKey && !apiKeyOverride) {
+      return {
+        fiberKey,
+        runId: row.runId,
+        agentId: row.agentId || null,
+        status: row.status,
+        result: null,
+        error: "This run was created with a per-user API key override; re-supply the same override to read its result (the server fallback key is never substituted)."
+      };
+    }
+    if (classifyStatus(row.status) !== "terminal") {
+      return {
+        fiberKey,
+        runId: row.runId,
+        agentId: row.agentId || null,
+        status: row.status,
+        result: null,
+        error: row.lastError
+      };
+    }
+    const client = this.client(apiKeyOverride);
+    try {
+      const result = await client.getRunResult(row.agentId, row.runId);
+      const noDiagnostic = row.status !== "completed" && result.error === null && result.outputType === "unknown";
+      return {
+        fiberKey,
+        runId: row.runId,
+        agentId: row.agentId || null,
+        status: row.status,
+        result,
+        error: noDiagnostic ? `Nimble run ended with status "${row.status}"; the result endpoint returned no diagnostic.` : result.error?.message ?? null
+      };
+    } catch (err) {
+      if (row.status === "completed") throw err;
+      return {
+        fiberKey,
+        runId: row.runId,
+        agentId: row.agentId || null,
+        status: row.status,
+        result: null,
+        error: row.lastError ?? (err instanceof Error ? err.message : "Nimble run failed; result details unavailable")
+      };
+    }
+  }
+  /**
+   * Resumes a "recovery-blocked" override-backed run once the caller
+   * re-supplies the same (or an equivalently authorized) API key. Never
+   * used to retry the create — only to resume polling an already-created
+   * run. See onFiberRecovered's fail-closed handling above.
+   */
+  async resumeWithOverride(fiberKey, apiKeyOverride) {
+    const row = this.state.runs[fiberKey];
+    if (!row?.runId) {
+      throw new Error("No run to resume for this fiberKey");
+    }
+    if (row.status !== "recovery-blocked") {
+      return this.getRunLifecycleStatus(fiberKey);
+    }
+    this.upsertLedger(fiberKey, { status: "running", lastError: null });
+    const controller = new AbortController();
+    await this.pollUntilTerminal(fiberKey, row.agentId, row.runId, controller.signal, apiKeyOverride);
+    return this.getRunLifecycleStatus(fiberKey);
+  }
+};
+export {
+  ACTIVE_STATES,
+  AmbiguousCreateError,
+  CreateRateLimitedError,
+  DEFAULT_BASE_URL,
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_RETRY_POLICY,
+  GatedFeatureError,
+  NIMBLE_CLIENT_SOURCE,
+  NIMBLE_ENTERPRISE_CONTACT_URL,
+  NimbleAgentAPIError,
+  NimbleAgentClient,
+  NimbleRunAgent,
+  PollTimeoutError,
+  SELECTABLE_EFFORTS,
+  TERMINAL_STATES,
+  classifyStatus,
+  deriveFiberKey,
+  normalizeRunResult,
+  resolvePollIntervalMs
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nimble-way/cloudflare-agents",
+  "version": "0.1.0",
+  "description": "Resumable Nimble Agent API V2 tools for Cloudflare Agents",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nimbleway/cloudflare-agents.git"
+  },
+  "files": ["dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external agents --external @nimble-way/nimble-js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src test --ext .ts",
+    "test": "vitest run",
+    "check": "npm run lint && npm run typecheck && npm run test && npm run build"
+  },
+  "dependencies": {
+    "@nimble-way/nimble-js": "1.2.0"
+  },
+  "peerDependencies": {
+    "agents": ">=0.20.0 <1"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.18.8",
+    "@cloudflare/workers-types": "^5.20260722.1",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "agents": "0.20.0",
+    "eslint": "^9.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.0",
+    "wrangler": "4.114.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}