@greatwait/ai-sdk-tool 0.0.0-stage → 0.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlowXO LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @greatwait/ai-sdk-tool
 
-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.
+One server-side Vercel AI SDK tool for scheduling a callback to an **existing GreatWait endpoint**. It does not create endpoints or check callback delivery. `status: "accepted"` means GreatWait accepted a schedule; it does not mean delivery completed.
+
+```sh
+npm install @greatwait/ai-sdk-tool ai
+```
+
+Use Node 22.13 or newer. Start with the live [JavaScript quickstart](https://docs.greatwait.dev/guides/javascript) for GreatWait endpoint and credential setup. A dedicated AI SDK scheduling guide is staged at `docs/site/drafts/ai-sdk.mdx` and will be served at `/guides/ai-sdk` after the package is available on npm and the docs release checks pass.
+
+From the repository root, `npm run check --workspace @greatwait/ai-sdk-tool` runs TypeScript, the ESM/declaration build, offline tests, and a model-mock example. The release path separately packs the compiled package and checks a clean external install.
+
+The example uses `MockLanguageModelV4`, a fake fetch, and an **in-memory fixture only**. It is not a durable intent store and contacts no model provider or GreatWait service.
+
+## Server-side interface
+
+```ts
+const persistedIntent =
+  await applicationStore.getOrCreateSchedulingIntent(userActionId);
+// The store must atomically persist this record before tool execution. It contains:
+// idempotencyKey, firstAttemptAtMs, originalInput, externalIdentifier.
+const scheduling = createGreatwaitScheduleTool({
+  apiKey: process.env.GREATWAIT_API_KEY!,
+  endpointId: process.env.GREATWAIT_ENDPOINT_ID!,
+  persistedIntent,
+});
+```
+
+The caller owns a durable, unique logical intent. Its key is 16–255 printable ASCII characters. Its `firstAttemptAtMs` and original input must be written durably before the first possible POST and retained after GreatWait's 24-hour receipt window. `externalIdentifier` is a unique non-secret host ID, at most 256 UTF-8 bytes, included in the schedule for read-based recovery. The tool snapshots these values at construction, so later mutation of the supplied object cannot change the request or replay window. The model can only repeat the persisted `delaySeconds` and short `data` message; changed arguments return `uncertain` without a POST because the original create may have succeeded. A same-body replay is allowed only **before** the 24-hour boundary. At or after expiry, the tool sends nothing and directs authoritative read-based recovery. Process-local `inFlight` sharing prevents concurrent calls on one tool instance from sending twice; a joining caller can stop waiting on its own abort signal while the shared POST continues. Cross-process safety depends on the caller's durable intent and GreatWait's idempotency receipt.
+
+The model-facing input is `delaySeconds` (integer 1–158,000,000) and a JSON object with `message` (1–2,000 characters) and optional `reference` (up to 128 characters). The server fixes the credential, endpoint, API origin, key, and original body. Request bytes are capped at 64 KiB. GreatWait may apply a lower organization payload allowance and refuse the request.
+
+One tool execution makes at most one POST with `redirect: "manual"`. A single deadline covers both fetch and response parsing (10 seconds by default, server configurable up to 30 seconds), and response bodies are capped at 32 KiB. A caller abort before sending returns `not_sent`; timeout or cancellation after send returns `uncertain`. `refused` is a non-ambiguous refusal of the current request; `idempotency_key_reused` can still mean an earlier create succeeded. Save accepted IDs durably, then use `schedules.read` and occurrence/attempt reads for delivery status. If uncertain, read by a known schedule ID; otherwise query `schedules.list` with `external_identifier` and trust absence only when the page reports `freshness.kind: "authoritative"`. A projected page cannot prove absence. Do not create a new key automatically.
+
+## Why this adapter
+
+The existing `@greatwait/api-client` is the general client, with generated operations and contract parsing. Its `schedules_create` path automatically retries replay-safe failures, and its `FetchRequestInit` does not expose redirect mode. This candidate uses a minimal direct fetch to the already published `POST /v1/schedules` to enforce one POST and redirect refusal. It adds no backend or broad client.
+
+The guide source is staged at `docs/site/drafts/ai-sdk.mdx` until npm publication makes its install and imports true for readers. The implementation and tests require no live model provider or GreatWait credential.

package/dist/index.d.ts

@@ -0,0 +1,360 @@
+import { z } from "zod";
+declare const inputSchema: z.ZodObject<{
+    delaySeconds: z.ZodNumber;
+    data: z.ZodObject<{
+        message: z.ZodString;
+        reference: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ScheduleInput = z.infer<typeof inputSchema>;
+export type ScheduleResult = {
+    status: "accepted";
+    scheduleId: string;
+    occurrenceId: string;
+    replayed: boolean;
+    note: string;
+} | {
+    status: "refused";
+    httpStatus: number;
+    code: string;
+    note: string;
+} | {
+    status: "not_sent";
+    note: string;
+} | {
+    status: "uncertain";
+    note: string;
+};
+/**
+ * The application must durably persist this record before exposing the tool.
+ * Keep it after GreatWait's receipt expires. `originalInput` is frozen into the
+ * request body at tool construction; a later model call cannot change it.
+ */
+export interface PersistedScheduleIntent {
+    readonly idempotencyKey: string;
+    readonly firstAttemptAtMs: number;
+    readonly originalInput: ScheduleInput;
+    /** Unique, non-secret host identifier for read-based recovery. */
+    readonly externalIdentifier: string;
+}
+export interface GreatwaitScheduleToolOptions {
+    /** Server-held credential with schedules:write. Never put it in model input. */
+    readonly apiKey: string;
+    /** Existing destination in this credential's project and environment. */
+    readonly endpointId: string;
+    readonly persistedIntent: PersistedScheduleIntent;
+    /** Server-only bound; defaults to 10 seconds and cannot exceed 30 seconds. */
+    readonly requestTimeoutMs?: number;
+    /** Test seams. Neither is exposed to the model. */
+    readonly fetchImpl?: typeof fetch;
+    readonly now?: () => number;
+}
+/** One execution makes at most one POST; no automatic retry follows uncertainty. */
+export declare function createGreatwaitScheduleTool(options: GreatwaitScheduleToolOptions): ({
+    deferLoading?: boolean;
+    title?: string;
+    providerOptions?: import("@ai-sdk/provider-utils").ProviderOptions;
+    metadata?: import("@ai-sdk/provider").JSONObject;
+    inputSchema: import("ai").FlexibleSchema<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }>;
+    contextSchema?: import("ai").FlexibleSchema<import("@ai-sdk/provider-utils").Context> | undefined;
+    needsApproval?: boolean | import("@ai-sdk/provider-utils").ToolNeedsApprovalFunction<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }, NoInfer<import("@ai-sdk/provider-utils").Context>> | undefined;
+    onInputStart?: ((options: import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: {
+            delaySeconds: number;
+            data: {
+                message: string;
+                reference?: string | undefined;
+            };
+        };
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: {
+            delaySeconds: number;
+            data: {
+                message: string;
+                reference?: string | undefined;
+            };
+        };
+        output: NoInfer<ScheduleResult>;
+    }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: import("ai").FlexibleSchema<ScheduleResult> | undefined;
+    execute: import("ai").ToolExecuteFunction<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }, ScheduleResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+} & {
+    description?: string | ((options: {
+        context: NoInfer<import("@ai-sdk/provider-utils").Context>;
+        experimental_sandbox?: import("ai").Experimental_SandboxSession;
+    }) => string) | undefined;
+    strict?: boolean;
+    inputExamples?: {
+        input: NoInfer<{
+            delaySeconds: number;
+            data: {
+                message: string;
+                reference?: string | undefined;
+            };
+        }>;
+    }[] | undefined;
+    id?: never;
+    isProviderExecuted?: never;
+    args?: never;
+    supportsDeferredResults?: never;
+} & {
+    type?: undefined | "function";
+} & {
+    execute: import("ai").ToolExecuteFunction<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }, ScheduleResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+}) | ({
+    deferLoading?: boolean;
+    title?: string;
+    providerOptions?: import("@ai-sdk/provider-utils").ProviderOptions;
+    metadata?: import("@ai-sdk/provider").JSONObject;
+    inputSchema: import("ai").FlexibleSchema<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }>;
+    contextSchema?: import("ai").FlexibleSchema<import("@ai-sdk/provider-utils").Context> | undefined;
+    needsApproval?: boolean | import("@ai-sdk/provider-utils").ToolNeedsApprovalFunction<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }, NoInfer<import("@ai-sdk/provider-utils").Context>> | undefined;
+    onInputStart?: ((options: import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: {
+            delaySeconds: number;
+            data: {
+                message: string;
+                reference?: string | undefined;
+            };
+        };
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: {
+            delaySeconds: number;
+            data: {
+                message: string;
+                reference?: string | undefined;
+            };
+        };
+        output: NoInfer<ScheduleResult>;
+    }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: import("ai").FlexibleSchema<ScheduleResult> | undefined;
+    execute: import("ai").ToolExecuteFunction<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }, ScheduleResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+} & {
+    description?: string | ((options: {
+        context: NoInfer<import("@ai-sdk/provider-utils").Context>;
+        experimental_sandbox?: import("ai").Experimental_SandboxSession;
+    }) => string) | undefined;
+    strict?: boolean;
+    inputExamples?: {
+        input: NoInfer<{
+            delaySeconds: number;
+            data: {
+                message: string;
+                reference?: string | undefined;
+            };
+        }>;
+    }[] | undefined;
+    id?: never;
+    isProviderExecuted?: never;
+    args?: never;
+    supportsDeferredResults?: never;
+} & {
+    type: "dynamic";
+} & {
+    execute: import("ai").ToolExecuteFunction<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }, ScheduleResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+}) | ({
+    deferLoading?: boolean;
+    title?: string;
+    providerOptions?: import("@ai-sdk/provider-utils").ProviderOptions;
+    metadata?: import("@ai-sdk/provider").JSONObject;
+    inputSchema: import("ai").FlexibleSchema<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }>;
+    contextSchema?: import("ai").FlexibleSchema<import("@ai-sdk/provider-utils").Context> | undefined;
+    needsApproval?: boolean | import("@ai-sdk/provider-utils").ToolNeedsApprovalFunction<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }, NoInfer<import("@ai-sdk/provider-utils").Context>> | undefined;
+    onInputStart?: ((options: import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: {
+            delaySeconds: number;
+            data: {
+                message: string;
+                reference?: string | undefined;
+            };
+        };
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: {
+            delaySeconds: number;
+            data: {
+                message: string;
+                reference?: string | undefined;
+            };
+        };
+        output: NoInfer<ScheduleResult>;
+    }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: import("ai").FlexibleSchema<ScheduleResult> | undefined;
+    execute: import("ai").ToolExecuteFunction<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }, ScheduleResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+} & {
+    type: "provider";
+    id: `${string}.${string}`;
+    args: Record<string, unknown>;
+    description?: never;
+    strict?: never;
+    inputExamples?: never;
+} & {
+    isProviderExecuted: false;
+    supportsDeferredResults?: never;
+} & {
+    execute: import("ai").ToolExecuteFunction<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }, ScheduleResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+}) | ({
+    deferLoading?: boolean;
+    title?: string;
+    providerOptions?: import("@ai-sdk/provider-utils").ProviderOptions;
+    metadata?: import("@ai-sdk/provider").JSONObject;
+    inputSchema: import("ai").FlexibleSchema<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }>;
+    contextSchema?: import("ai").FlexibleSchema<import("@ai-sdk/provider-utils").Context> | undefined;
+    needsApproval?: boolean | import("@ai-sdk/provider-utils").ToolNeedsApprovalFunction<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }, NoInfer<import("@ai-sdk/provider-utils").Context>> | undefined;
+    onInputStart?: ((options: import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: {
+            delaySeconds: number;
+            data: {
+                message: string;
+                reference?: string | undefined;
+            };
+        };
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: {
+            delaySeconds: number;
+            data: {
+                message: string;
+                reference?: string | undefined;
+            };
+        };
+        output: NoInfer<ScheduleResult>;
+    }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: import("ai").FlexibleSchema<ScheduleResult> | undefined;
+    execute: import("ai").ToolExecuteFunction<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }, ScheduleResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+} & {
+    type: "provider";
+    id: `${string}.${string}`;
+    args: Record<string, unknown>;
+    description?: never;
+    strict?: never;
+    inputExamples?: never;
+} & {
+    isProviderExecuted: true;
+    supportsDeferredResults?: boolean;
+} & {
+    execute: import("ai").ToolExecuteFunction<{
+        delaySeconds: number;
+        data: {
+            message: string;
+            reference?: string | undefined;
+        };
+    }, ScheduleResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+});
+export {};

package/dist/index.js

@@ -0,0 +1,277 @@
+import { tool } from "ai";
+import { z } from "zod";
+const API_URL = "https://api.greatwait.dev/v1/schedules";
+const MAX_DELAY_SECONDS = 158_000_000;
+const MAX_JSON_BYTES = 64 * 1024;
+const MAX_RESPONSE_BYTES = 32 * 1024;
+const RECEIPT_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 10_000;
+const idempotencyKeySchema = z
+    .string()
+    .min(16)
+    .max(255)
+    .regex(/^[\x20-\x7e]+$/u);
+const inputSchema = z
+    .object({
+    delaySeconds: z.number().int().min(1).max(MAX_DELAY_SECONDS),
+    data: z
+        .object({
+        message: z.string().min(1).max(2_000),
+        reference: z.string().max(128).optional(),
+    })
+        .strict(),
+})
+    .strict();
+const publicCodes = new Set([
+    "authentication_required",
+    "credential_expired",
+    "credential_revoked",
+    "idempotency_key_reused",
+    "invalid_request",
+    "not_found",
+    "plan_limit_reached",
+    "project_archived",
+    "state_conflict",
+    "rate_limited",
+    "scope_missing",
+    "capability_not_configured",
+    "service_unavailable",
+]);
+function safeCode(value) {
+    return typeof value === "string" && publicCodes.has(value)
+        ? value
+        : "request_refused";
+}
+function isId(value, prefix) {
+    return (typeof value === "string" &&
+        new RegExp(`^${prefix}[0-9abcdefghjkmnpqrstvwxyz]{26}$`, "u").test(value));
+}
+function makeBody(input, endpoint, externalIdentifier) {
+    return JSON.stringify({
+        delaySeconds: input.delaySeconds,
+        endpoint,
+        external_identifier: externalIdentifier,
+        data: {
+            message: input.data.message,
+            ...(input.data.reference === undefined
+                ? {}
+                : { reference: input.data.reference }),
+        },
+    });
+}
+const uncertain = (note) => ({
+    status: "uncertain",
+    note,
+});
+async function readJsonBounded(response, interrupted) {
+    if (!response.body)
+        throw new Error("Empty response body");
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const part = await Promise.race([reader.read(), interrupted]);
+            if (part.done)
+                break;
+            size += part.value.byteLength;
+            if (size > MAX_RESPONSE_BYTES)
+                throw new Error("Response body too large");
+            chunks.push(part.value);
+        }
+        const bytes = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    finally {
+        // A timed-out mock can ignore cancellation. Do not wait for it or keep the tool open.
+        void reader.cancel().catch(() => { });
+    }
+}
+/** One execution makes at most one POST; no automatic retry follows uncertainty. */
+export function createGreatwaitScheduleTool(options) {
+    if (typeof window !== "undefined")
+        throw new Error("GreatWait tool is server-only");
+    const apiKey = options.apiKey;
+    const endpointId = options.endpointId;
+    if (!apiKey || /[\r\n]/u.test(apiKey))
+        throw new Error("Invalid server credential");
+    if (!/^ep_[0-9abcdefghjkmnpqrstvwxyz]{26}$/u.test(endpointId))
+        throw new Error("Invalid configured endpoint ID");
+    // Snapshot every value used after construction; readonly TypeScript fields do
+    // not prevent a caller from mutating the supplied object at runtime.
+    const idempotencyKey = idempotencyKeySchema.parse(options.persistedIntent.idempotencyKey);
+    const firstAttemptAtMs = options.persistedIntent.firstAttemptAtMs;
+    const externalIdentifier = options.persistedIntent.externalIdentifier;
+    if (!Number.isSafeInteger(firstAttemptAtMs) || firstAttemptAtMs < 0)
+        throw new Error("Invalid persisted first-attempt time");
+    if (!externalIdentifier ||
+        Buffer.byteLength(externalIdentifier, "utf8") > 256 ||
+        /[\r\n]/u.test(externalIdentifier)) {
+        throw new Error("Invalid persisted external identifier");
+    }
+    const originalInput = inputSchema.parse(options.persistedIntent.originalInput);
+    const body = makeBody(originalInput, endpointId, externalIdentifier);
+    if (Buffer.byteLength(body, "utf8") > MAX_JSON_BYTES)
+        throw new Error("Persisted request exceeds the JSON limit");
+    const timeoutMs = options.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30_000)
+        throw new Error("Invalid server timeout");
+    const now = options.now ?? Date.now;
+    const send = options.fetchImpl ?? fetch;
+    let inFlight;
+    async function awaitShared(pending, callerSignal) {
+        if (!callerSignal)
+            return pending;
+        const stopped = () => uncertain("This call stopped waiting for a shared create. It may still be accepted; recover the persisted intent before any new create.");
+        if (callerSignal.aborted)
+            return stopped();
+        let onAbort = () => { };
+        const interrupted = new Promise((resolve) => {
+            onAbort = () => resolve(stopped());
+            callerSignal.addEventListener("abort", onAbort, { once: true });
+            if (callerSignal.aborted)
+                onAbort();
+        });
+        try {
+            return await Promise.race([pending, interrupted]);
+        }
+        finally {
+            callerSignal.removeEventListener("abort", onAbort);
+        }
+    }
+    async function sendOnce(callerSignal) {
+        const controller = new AbortController();
+        const onCallerAbort = () => controller.abort();
+        callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+        if (callerSignal?.aborted)
+            controller.abort();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        const interrupted = new Promise((_, reject) => {
+            if (controller.signal.aborted)
+                reject(new Error("interrupted"));
+            else
+                controller.signal.addEventListener("abort", () => reject(new Error("interrupted")), { once: true });
+        });
+        try {
+            if (controller.signal.aborted)
+                return {
+                    status: "not_sent",
+                    note: "The request was cancelled before sending.",
+                };
+            const response = await Promise.race([
+                send(API_URL, {
+                    method: "POST",
+                    redirect: "manual",
+                    signal: controller.signal,
+                    headers: {
+                        Authorization: `Bearer ${apiKey}`,
+                        "Content-Type": "application/json",
+                        "Idempotency-Key": idempotencyKey,
+                    },
+                    body,
+                }),
+                interrupted,
+            ]);
+            if (response.status >= 300 && response.status < 400) {
+                return uncertain("A redirect was refused. Recover using the persisted identifier before any new create.");
+            }
+            if (response.status >= 500 ||
+                response.status === 408 ||
+                response.status === 499 ||
+                response.status === 0) {
+                return uncertain("The server outcome is unclear. Recover using the persisted identifier before any new create.");
+            }
+            if (!response.ok) {
+                let code;
+                try {
+                    code = (await readJsonBounded(response, interrupted)).code;
+                }
+                catch {
+                    if (controller.signal.aborted)
+                        return uncertain("The response was interrupted. Recover using the persisted identifier.");
+                }
+                const publicCode = safeCode(code);
+                return {
+                    status: "refused",
+                    httpStatus: response.status,
+                    code: publicCode,
+                    note: publicCode === "idempotency_key_reused"
+                        ? "This request was refused; an earlier create using this key may have succeeded. Recover the original intent."
+                        : "GreatWait refused the create request. No delivery was confirmed.",
+                };
+            }
+            let value;
+            try {
+                value = await readJsonBounded(response, interrupted);
+            }
+            catch {
+                return uncertain("The success response was interrupted or malformed. Recover using the persisted identifier.");
+            }
+            if (typeof value !== "object" || value === null)
+                return uncertain("The success response was malformed. Recover using the persisted identifier.");
+            const record = value;
+            if (!isId(record.schedule?.id, "sch_") ||
+                !isId(record.occurrence?.id, "occ_") ||
+                record.occurrence?.schedule !== record.schedule.id ||
+                (record.schedule.endpoint !== undefined &&
+                    record.schedule.endpoint !== endpointId) ||
+                (record.schedule.external_identifier !== undefined &&
+                    record.schedule.external_identifier !== externalIdentifier)) {
+                return uncertain("The success response had inconsistent identifiers. Recover using the persisted identifier.");
+            }
+            return {
+                status: "accepted",
+                scheduleId: record.schedule.id,
+                occurrenceId: record.occurrence.id,
+                replayed: response.headers.get("Idempotency-Replayed") === "true",
+                note: "GreatWait accepted the schedule. Callback delivery has not been confirmed.",
+            };
+        }
+        catch {
+            return uncertain("No reliable response was received. Recover using the persisted identifier before any new create.");
+        }
+        finally {
+            clearTimeout(timeout);
+            callerSignal?.removeEventListener("abort", onCallerAbort);
+        }
+    }
+    return tool({
+        description: "Schedule one future GreatWait callback to the server's configured endpoint. Acceptance means scheduled, not delivered.",
+        inputSchema,
+        execute: async (untrustedInput, executionOptions) => {
+            const input = inputSchema.parse(untrustedInput);
+            const proposedBody = makeBody(input, endpointId, externalIdentifier);
+            if (proposedBody !== body) {
+                return uncertain("The model changed the persisted request. Its original create may have succeeded; recover that intent before proposing another.");
+            }
+            if (executionOptions.abortSignal?.aborted) {
+                if (inFlight)
+                    return uncertain("This call was cancelled while another call for the same intent was in flight. That shared create may still be accepted.");
+                return {
+                    status: "not_sent",
+                    note: "This tool call was cancelled before sending. An earlier call for the same intent may still exist.",
+                };
+            }
+            const ageMs = now() - firstAttemptAtMs;
+            if (!Number.isFinite(ageMs) || ageMs < 0 || ageMs >= RECEIPT_MS) {
+                return uncertain("The idempotency receipt window has expired or its clock is invalid. No POST was sent; use authoritative read-based recovery.");
+            }
+            if (inFlight)
+                return awaitShared(inFlight, executionOptions.abortSignal);
+            const pending = sendOnce(executionOptions.abortSignal);
+            inFlight = pending;
+            try {
+                return await pending;
+            }
+            finally {
+                if (inFlight === pending)
+                    inFlight = undefined;
+            }
+        },
+    });
+}

package/package.json

@@ -1,6 +1,48 @@
 {
+  "bugs": {
+    "url": "https://github.com/flowxo/greatwait/issues"
+  },
+  "dependencies": {
+    "ai": "7.0.146",
+    "zod": "4.4.3"
+  },
+  "description": "Server-side Vercel AI SDK tool for submitting a bounded GreatWait callback schedule to an existing endpoint.",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist"
+  ],
+  "homepage": "https://greatwait.dev",
+  "keywords": [
+    "greatwait",
+    "scheduling",
+    "ai-sdk",
+    "tools",
+    "webhooks"
+  ],
+  "license": "MIT",
   "name": "@greatwait/ai-sdk-tool",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flowxo/greatwait.git",
+    "directory": "packages/ai-sdk-tool"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "version": "0.3.3"
+}