nanocodex 0.4.0 → 0.6.0

package/types.d.mts

@@ -1,6 +1,6 @@
 export type Thinking = "none" | "low" | "medium" | "high" | "xhigh" | "max";
 export type ReasoningMode = "standard" | "pro";
-export type Model = "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna";
+export type Model = "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna" | "gpt-6-astra";
 
 export type PromptItem =
   | { type: "text"; text: string }
@@ -18,7 +18,10 @@ export type AgentEvent = {
 };
 
 export type AgentOptions = {
+  /** Replaces the selected model's built-in instructions. */
   instructions?: string | undefined;
+  /** Appends host instructions while retaining the selected model's prompt. */
+  additionalInstructions?: string | undefined;
   model?: Model | undefined;
   reasoningMode?: ReasoningMode | undefined;
   fastMode?: boolean | undefined;
@@ -28,13 +31,248 @@ export type AgentOptions = {
   resume?: SessionSnapshot | undefined;
 };
 
+/** Model-visible facts for tools executing outside the embedding process. */
+export type ExecutionEnvironment = Readonly<{
+  currentDate: string;
+  timezone: string;
+  projectInstructions?: string | undefined;
+}>;
+
+/** Unsigned decimal revision. Strings preserve the complete Rust `u64` range. */
+declare const durabilityRevisionBrand: unique symbol;
+export type DurabilityRevision = string & {
+  readonly [durabilityRevisionBrand]: "NanocodexDurabilityRevision";
+};
+
+/** Unsigned decimal owner generation. Strings preserve the complete Rust `u64` range. */
+declare const durabilityFenceBrand: unique symbol;
+export type DurabilityFence = string & {
+  readonly [durabilityFenceBrand]: "NanocodexDurabilityFence";
+};
+
+export type DurabilityStoredState = Readonly<{
+  revision: DurabilityRevision;
+  payload: string | null;
+}>;
+
+/** JSON-safe exact state archive used for an offline provider cutover. */
+export type DurabilityPortableStateArchive = DurabilityStoredState & Readonly<{
+  format: "nanocodex-durability-state-v2";
+  stateId: string;
+  records: readonly DurabilityRecord[];
+}>;
+
+export type DurabilityExportCursor = string;
+
+/** One deterministic page of the total-state replacement from `from` (exclusive) to `to` (inclusive). */
+export type DurabilityPortableStatePage = Readonly<{
+  format: "nanocodex-durability-state-page-v2";
+  stateId: string;
+  from: DurabilityRevision;
+  /** SHA-256 over the UTF-8 JSON tuple `[from, fromPayload]`. */
+  fromDigest: string;
+  to: DurabilityRevision;
+  cursor: DurabilityExportCursor;
+  nextCursor: DurabilityExportCursor | null;
+  /** Total UTF-16 code units in the opaque state payload. */
+  payloadLength: number;
+  payload: string;
+  records: readonly DurabilityRecord[];
+}>;
+
+export type DurabilityExportPageRequest = Readonly<{
+  from: DurabilityRevision;
+  /** Digest of the exact state at `from`; omit only when `from` is revision zero. */
+  fromDigest?: string | undefined;
+  /** Omit on the first request to select the current source revision; repeat the returned `to`. */
+  to?: DurabilityRevision | undefined;
+  cursor?: DurabilityExportCursor | undefined;
+  /** UTF-16 code units per page. Defaults to 256 KiB and is capped at 1 MiB. */
+  limit?: number | undefined;
+}>;
+
+export type DurabilityAcquireRequest = Readonly<{
+  ownerId: string;
+}>;
+
+export type DurabilityAcquiredState = DurabilityStoredState & Readonly<{
+  ownerId: string;
+  fence: DurabilityFence;
+}>;
+
+export type DurabilityRecord = Readonly<{ key: string; value: string }>;
+
+export type DurabilityReplaceRequest = Readonly<{
+  records: readonly DurabilityRecord[];
+  ownerId: string;
+  fence: DurabilityFence;
+  expectedRevision: DurabilityRevision;
+  payload: string;
+}>;
+
+export type DurabilityReplaceResult =
+  | Readonly<{ status: "replaced"; revision: DurabilityRevision }>
+  | Readonly<{ status: "fenced" }>
+  | Readonly<{ status: "conflict"; actualRevision: DurabilityRevision }>
+  | Readonly<{ status: "not_committed"; message: string }>;
+
+/** Host capability consumed by the Rust/WASM durability driver. */
+export type DurabilityStore = Readonly<{
+  readRecord(stateId: string, key: string): string | null | Promise<string | null>;
+  /** Optional single-query implementation; Rust requests at most 16 records. */
+  readRecords?(stateId: string, keys: readonly string[]): readonly (string | null)[] | Promise<readonly (string | null)[]>;
+  load(stateId: string): DurabilityStoredState | Promise<DurabilityStoredState>;
+  acquire(
+    stateId: string,
+    request: DurabilityAcquireRequest,
+  ): DurabilityAcquiredState | Promise<DurabilityAcquiredState>;
+  replace(
+    stateId: string,
+    request: DurabilityReplaceRequest,
+  ): DurabilityReplaceResult | Promise<DurabilityReplaceResult>;
+}>;
+
+/** Store that can atomically restore an exact revision into an empty destination. */
+export type DurabilityPortableStore = DurabilityStore & Readonly<{
+  scanRecords(stateId: string, after?: string, limit?: number): readonly DurabilityRecord[] | Promise<readonly DurabilityRecord[]>;
+  importRecords(stateId: string, records: readonly DurabilityRecord[]): void | Promise<void>;
+  importState(
+    stateId: string,
+    state: DurabilityStoredState,
+    options?: Readonly<{
+      records?: readonly DurabilityRecord[];
+      expectedRevision?: DurabilityRevision | undefined;
+      /** When supplied, compare the complete expected state atomically before importing. */
+      expectedPayload?: string | null | undefined;
+    }> | undefined,
+  ): DurabilityStoredState | Promise<DurabilityStoredState>;
+}>;
+
+/** In-process store for hosts that carry its snapshot across durable steps. */
+export type MemoryDurabilityStore = DurabilityPortableStore & Readonly<{
+  stateId: string;
+  snapshot(): DurabilityStoredState;
+}>;
+
+/**
+ * SQLite scalar accepted by the generic adapter. Revision and fence numbers
+ * must be nonnegative safe integers; return exact decimal TEXT for larger values.
+ */
+export type DurabilitySqliteValue = string | number | null;
+export type DurabilitySqliteRow = Record<string, DurabilitySqliteValue>;
+
+export type DurabilitySqliteQuery = <Row extends DurabilitySqliteRow>(
+  sql: string,
+  args: readonly DurabilitySqliteValue[],
+) => readonly Row[] | Promise<readonly Row[]>;
+
+export type DurabilitySqliteTransaction = <Result>(
+  callback: (query: DurabilitySqliteQuery) => Result | Promise<Result>,
+) => Result | Promise<Result>;
+
+export type SqliteDurabilityStoreOptions = Readonly<{
+  transaction: DurabilitySqliteTransaction;
+}>;
+
+/** Unsigned decimal revision for opaque ChatGPT subscription state. */
+declare const subscriptionRevisionBrand: unique symbol;
+export type SubscriptionRevision = string & {
+  readonly [subscriptionRevisionBrand]: "NanocodexSubscriptionRevision";
+};
+
+export type SubscriptionStoredValue = Readonly<{
+  revision: SubscriptionRevision;
+  payload?: string | undefined;
+}>;
+
+export type SubscriptionCommitRequest = Readonly<{
+  expectedRevision: SubscriptionRevision;
+  /** Opaque Rust-owned credential state. Hosts must store it as a secret. */
+  payload: string;
+}>;
+
+export type SubscriptionCommitResult =
+  | Readonly<{ status: "committed"; revision: SubscriptionRevision }>
+  | Readonly<{ status: "conflict"; actualRevision: SubscriptionRevision }>;
+
+/** Generic secret persistence consumed by the Rust ChatGPT lifecycle. */
+export type ChatGptSubscriptionStore = Readonly<{
+  load(id: string): SubscriptionStoredValue | Promise<SubscriptionStoredValue>;
+  compareAndSwap(
+    id: string,
+    request: SubscriptionCommitRequest,
+  ): SubscriptionCommitResult | Promise<SubscriptionCommitResult>;
+}>;
+
+export type MemoryChatGptSubscriptionStore = ChatGptSubscriptionStore & Readonly<{
+  id: string;
+  snapshot(): SubscriptionStoredValue;
+}>;
+
+export type ChatGptCredentialSeed = Readonly<{
+  accessToken: string;
+  refreshToken?: string | undefined;
+  accountId: string;
+  fedramp?: boolean | undefined;
+}>;
+
+export type ChatGptLoginStatus =
+  | Readonly<{ state: "signed_out" | "expired" }>
+  | Readonly<{
+      state: "pending";
+      verificationUrl: string;
+      userCode: string;
+      expiresAt: number;
+      pollAfterMs: number;
+    }>
+  | Readonly<{
+      state: "authenticated";
+      accountId: string;
+      expiresAt: number | null;
+    }>;
+
+export type ChatGptCredential = Readonly<{
+  kind: "chatgpt";
+  /** Resolved bearer credential. Do not retain or log it. */
+  accessToken: string;
+  accountId: string;
+  fedramp: boolean;
+  revision: SubscriptionRevision;
+}>;
+
+export type ChatGptSubscriptionHandle = Readonly<{
+  id: string;
+  startLogin(): Promise<ChatGptLoginStatus>;
+  status(): Promise<ChatGptLoginStatus>;
+  credential(): Promise<ChatGptCredential>;
+  recover(rejectedRevision: SubscriptionRevision): Promise<ChatGptCredential>;
+  logout(): Promise<void>;
+  dispose(): void;
+}>;
+
+export type ChatGptSubscriptionOptions = Readonly<{
+  id: string;
+  store: ChatGptSubscriptionStore;
+  /** Generic bounded HTTP capability; defaults to global fetch. */
+  fetch?: typeof globalThis.fetch | undefined;
+  /**
+   * Trusted initial credentials, typically imported from Codex auth.json.
+   * A same-account seed repairs stored access-only credentials; refreshable durable state wins.
+   */
+  seed?: ChatGptCredentialSeed | undefined;
+  /** Test-only local issuer override. */
+  issuer?: string | undefined;
+  /** Browser WASM module compiled from the same nanocodex package. */
+  module?: unknown;
+}>;
+
 export type EstimatedUsdCost = Readonly<{
   usd: string;
   input_usd: string;
   cached_input_usd: string;
   cache_write_input_usd: string;
   output_usd: string;
-  service_tier: "standard" | "priority";
+  service_tier: "standard" | "priority" | "fast";
 }>;
 
 export type CostStatus =
@@ -64,9 +302,20 @@ export type TurnUsage = Readonly<{
   cost_status: CostStatus;
 }>;
 
-export type ForkOptions = { at?: TurnResult | undefined };
+export type ForkOptions = Readonly<{ at?: TurnResult | undefined }>;
 export type WatchEventsOptions = { includeAllSessions?: boolean | undefined };
 
+/** Read-only model context captured at the latest safe agent boundary. */
+export type AgentSessionContext = Readonly<{
+  workspace: string;
+  history: readonly Record<string, unknown>[];
+}>;
+
+export type RealtimeTranscriptEntry = Readonly<{
+  role: "user" | "assistant";
+  text: string;
+}>;
+
 export type EventWatcher = Readonly<{
   onEvent(listener: (event: AgentEvent) => void): () => void;
   off(): void;
@@ -78,19 +327,37 @@ export type AgentActions = {
     watch(options?: WatchEventsOptions): EventWatcher;
   };
   session: {
+    appendDeveloperMessage(text: string): Promise<AgentSessionContext>;
     compact(): Promise<void>;
+    context(): Promise<AgentSessionContext>;
     fork(options?: ForkOptions): Promise<DefaultAgent>;
+    setModel(model: Model): Promise<void>;
     setFastMode(enabled: boolean): Promise<void>;
     setThinking(thinking: Thinking): Promise<void>;
     shutdown(): Promise<void>;
     spawn(): Promise<DefaultAgent>;
+    realtime: {
+      start(): Promise<AgentSessionContext>;
+      end(): Promise<AgentSessionContext>;
+      delegation(
+        input: string,
+        transcript?: readonly RealtimeTranscriptEntry[],
+      ): Promise<string>;
+      tailDelegation(
+        transcript: readonly RealtimeTranscriptEntry[],
+      ): Promise<string | undefined>;
+    };
   };
   turn: {
-    prompt(options: { input: PromptInput }): Turn;
+    prompt(options: {
+      input: PromptInput;
+      id?: string | undefined;
+    }): Turn;
   };
 };
 
 export type Agent<extended extends object = {}> = {
+  readonly agentId: string;
   readonly key: string;
   readonly name: string;
   readonly sessionId: string;
@@ -105,34 +372,182 @@ export type Agent<extended extends object = {}> = {
 
 export type DefaultAgent = Agent<AgentActions>;
 
+/** Transport-independent Agent lifecycle shared by local and managed durable Agents. */
+export type AgentLifecycle = {
+  readonly agentId: string;
+  readonly key: string;
+  readonly name: string;
+  readonly sessionId: string;
+  readonly type: string;
+  readonly uid: string;
+  dispose(): void;
+  events: {
+    watch(options?: WatchEventsOptions): EventWatcher;
+  };
+  session: {
+    /** Stops this client lifecycle. A managed shutdown never deletes the durable Agent. */
+    shutdown(): Promise<void>;
+  };
+  turn: {
+    prompt(options: {
+      input: PromptInput;
+      id?: string | undefined;
+    }): LifecycleTurn;
+  };
+};
+
+export type LifecycleTurn = Readonly<{
+  readonly agent: Readonly<{
+    agentId: string;
+    key: string;
+    name: string;
+    sessionId: string;
+    type: string;
+    uid: string;
+    dispose(): void;
+  }>;
+  accepted(): Promise<string | undefined>;
+  result(): Promise<LifecycleTurnResult>;
+  steer(options: { input: PromptInput; messageId?: string }): Promise<void>;
+  /** Removes this identified steer only while it is still pending. */
+  withdrawSteer(options: { messageId: string }): Promise<boolean>;
+  cancel(): Promise<void>;
+  dispose(): void;
+}>;
+
+export type LifecycleTurnResult = Readonly<{
+  finalMessage: string;
+  /** Managed Agents may return null when the service did not report usage. */
+  usage(): Promise<TurnUsage | null>;
+  dispose(): void;
+}>;
+
 export type Turn<agent extends Agent<object> = Agent<object>> = Readonly<{
   readonly agent: agent;
+  /**
+   * Waits for execution-policy admission and returns its durable request ID.
+   * Rejections are Errors whose `code` is `cancelled`, `blocked`, `conflict`,
+   * `retryable`, `reopen_required`, `invalid_request`, or `failed`.
+   */
+  accepted(): Promise<string | undefined>;
+  /**
+   * Waits for the terminal result. A `reopen_required` rejection means this
+   * Agent is stale and the same durable turn may be resumed only on a new Agent.
+   */
   result(): Promise<TurnResult>;
-  steer(options: { input: PromptInput }): Promise<void>;
+  steer(options: { input: PromptInput; messageId?: string }): Promise<void>;
+  /** Removes this identified steer only while it is still pending. */
+  withdrawSteer(options: { messageId: string }): Promise<boolean>;
   cancel(): Promise<void>;
   /** Releases this handle without cancelling its accepted turn. */
   dispose(): void;
 }>;
 
+declare const turnResultBrand: unique symbol;
+/** Opaque completed-turn identity. Materialize large values explicitly and release it when done. */
 export type TurnResult = Readonly<{
+  readonly [turnResultBrand]: "NanocodexTurnResult";
   finalMessage: string;
-  snapshot: SessionSnapshot;
-  usage: TurnUsage;
+  snapshot(): Promise<SessionSnapshot>;
+  usage(): Promise<TurnUsage>;
+  dispose(): void;
 }>;
 
-export type ToolContext = {
-  callId: string;
-  parentCallId: string;
-  sessionId: string;
+import type { NamedTool, ToolMap } from "nanocodex-tools";
+export type {
+  NamedTool,
+  SubagentToolContext,
+  Tool,
+  ToolContext,
+  ToolMap,
+} from "nanocodex-tools";
+
+/** Static JavaScript tools, optionally composed with Rust-backed extensions. */
+export type ToolConfiguration<Extension = never> =
+  | ToolMap
+  | readonly (NamedTool | Extension)[]
+  | import("./tools/Tools.mjs").Tools;
+
+export type CodeEvaluatorEnvironment = {
+  tools: Readonly<Record<string, (input: unknown) => Promise<unknown>>>;
+  toolDefinitions: readonly Record<string, unknown>[];
+  text(value: unknown): void;
+  image(value: unknown, detail?: string): void;
+  generatedImage(value: unknown): void;
+  audio(value: unknown): void;
+  notify(value: unknown): void;
+  yield_control(): void;
+  setTimeout(callback: () => void, delayMs?: number): number;
+  clearTimeout(timerId?: number): void;
+  store(key: string, value: unknown): void;
+  load(key: string): unknown;
+  exit(): never;
+  require?: unknown;
+  console?: Console;
+  /** Aborts the exact active Code Mode cell and all nested tool calls. */
+  signal: AbortSignal;
+};
+
+export type CodeEvaluator = (
+  source: string,
+  environment: CodeEvaluatorEnvironment,
+) => void | Promise<void>;
+
+export type McpPayment = {
+  /** MPPx client methods, such as `tempo.session({ account, getClient, channelStore })`. */
+  methods: readonly unknown[];
+  /** Optional MPP method context forwarded for each paid MCP tool call. */
+  context?: unknown;
+  /** Called before MPPx creates a payment credential. */
+  onPaymentRequired?: ((challenge: unknown) => boolean | Promise<boolean>) | undefined;
+  orderChallenges?: ((challenges: readonly unknown[]) => readonly unknown[] | Promise<readonly unknown[]>) | undefined;
+  paymentPreferences?: unknown;
+};
+
+export type McpClient = {
+  listTools(params?: { cursor?: string | undefined }, options?: Record<string, unknown>): Promise<{
+    tools: readonly McpTool[];
+    nextCursor?: string | undefined;
+  }>;
+  callTool(
+    params: { name: string; arguments?: Record<string, unknown> | undefined },
+    resultSchema?: unknown,
+    options?: Record<string, unknown>,
+  ): Promise<unknown>;
+};
+
+export type McpTool = {
+  name: string;
+  title?: string | undefined;
+  description?: string | undefined;
+  inputSchema?: Record<string, unknown> | undefined;
+  annotations?: Readonly<Record<string, unknown>> & {
+    readOnlyHint?: boolean | undefined;
+  } | undefined;
 };
 
-export type Tool = {
-  description: string;
-  parameters: Record<string, unknown>;
-  handler(input: unknown, context: ToolContext): unknown | Promise<unknown>;
+export type McpServer = {
+  /** Public Streamable HTTP MCP endpoint. Omit when supplying an initialized client. */
+  url?: string | URL | undefined;
+  /** Existing MCP SDK-compatible client; Nanocodex does not close caller-owned clients. */
+  client?: McpClient | undefined;
+  description?: string | undefined;
+  headers?: HeadersInit | undefined;
+  fetch?: typeof globalThis.fetch | undefined;
+  payment?: McpPayment | undefined;
+  enabledTools?: readonly string[] | undefined;
+  disabledTools?: readonly string[] | undefined;
+  /** Declares every remote tool on this server safe for concurrent nested calls. */
+  supportsParallelToolCalls?: boolean | undefined;
+  /** Declares specific remote tool names safe for concurrent nested calls. */
+  parallelTools?: readonly string[] | undefined;
+  /** Synchronously reports whether this server may currently be discovered or called. */
+  isAvailable?: (() => boolean) | undefined;
+  startupTimeoutMs?: number | undefined;
+  timeoutMs?: number | undefined;
 };
 
-export type ToolMap = Record<string, Tool>;
+export type McpServers = Record<string, string | URL | McpServer>;
 
 /** A paid WebSocket session, such as an mppx Tempo session manager. */
 export type MppSession = {

package/worker/ChatGptSubscription.d.mts

@@ -0,0 +1,9 @@
+import type {
+  ChatGptSubscriptionHandle,
+  ChatGptSubscriptionOptions,
+} from "../types.mjs";
+
+/** Opens the Rust-owned ChatGPT lifecycle in a module Worker. */
+export function open(
+  options: Omit<ChatGptSubscriptionOptions, "module"> & { module: WebAssembly.Module },
+): Promise<ChatGptSubscriptionHandle>;

package/worker/ChatGptSubscription.mjs

@@ -0,0 +1,29 @@
+import init, { ChatGptSubscription as WasmChatGptSubscription } from "../pkg-web/nanocodex.js";
+
+import { installHostBridge } from "../internal.mjs";
+import { openSubscription } from "../runtime/chatgpt-subscription.mjs";
+
+let initialization;
+
+/** Opens the Rust-owned ChatGPT lifecycle in a module Worker. */
+export async function open(options) {
+  installHostBridge();
+  if (options?.module === undefined) {
+    throw new TypeError("Worker ChatGptSubscription requires a precompiled WASM module");
+  }
+  await initialize(options.module);
+  return openSubscription(
+    options,
+    (config) => WasmChatGptSubscription.open(config),
+    // A Cloudflare isolate can outlive an evicted Durable Object instance.
+    // Rebind its stable subscription ID to the reconstructed instance.
+    { replaceHost: true },
+  );
+}
+
+function initialize(module) {
+  return initialization ??= init({ module_or_path: module }).catch((error) => {
+    initialization = undefined;
+    throw error;
+  });
+}

package/worker/index.d.mts

@@ -0,0 +1,18 @@
+export {
+  createMemoryChatGptSubscriptionStore,
+  subscriptionRevision,
+} from "../runtime/subscription-store.mjs";
+export type {
+  ChatGptCredential,
+  ChatGptCredentialSeed,
+  ChatGptLoginStatus,
+  ChatGptSubscriptionHandle,
+  ChatGptSubscriptionOptions,
+  ChatGptSubscriptionStore,
+  MemoryChatGptSubscriptionStore,
+  SubscriptionCommitRequest,
+  SubscriptionCommitResult,
+  SubscriptionRevision,
+  SubscriptionStoredValue,
+} from "../types.mjs";
+export * as ChatGptSubscription from "./ChatGptSubscription.mjs";

package/worker/index.mjs

@@ -0,0 +1,5 @@
+export {
+  createMemoryChatGptSubscriptionStore,
+  subscriptionRevision,
+} from "../runtime/subscription-store.mjs";
+export * as ChatGptSubscription from "./ChatGptSubscription.mjs";