@opengeni/codemode 0.4.22 → 0.4.27-canary.0

package/README.md

@@ -5,9 +5,10 @@ catalog from the exact tools admitted to an execution attempt and dispatches
 both model MCP calls and sandbox Codemode calls through the same opaque tool
 identities and executors.
 
-The package owns deterministic catalog projection, collision-safe JavaScript
-paths, catalog digests, stale-catalog fencing, approval classification, and
-result-shape preservation. It does not discover MCP servers, resolve
+The package owns deterministic catalog projection, normalized unique JavaScript
+paths with path-prefix collisions rejected during catalog creation, catalog
+digests, stale-catalog fencing, approval classification, and result-shape
+preservation. It does not discover MCP servers, resolve
 credentials, persist attempts, or bypass host authorization; callers provide
 the already-admitted definitions and one authorization hook.
 
@@ -29,6 +30,31 @@ Generate digest-pinned project declarations from the live attempt catalog with
 `ogtool declarations opengeni-codemode.d.ts`. Runtime schema validation remains
 authoritative when a script outlives a catalog generation.
 
+When submission receives the structured `codemode_catalog_stale` response, the
+client refreshes the catalog once, re-resolves the requested identity or
+namespace path, and retries with the same caller-owned operation id. The API
+emits that code only before creating an operation. Ambiguous transport failures
+may be reconciled by operation id only when the recovered row exactly matches
+the requested attempt scope, catalog digest, tool identity, and canonical
+arguments. Deterministic HTTP conflicts are returned directly and never adopt an
+existing operation during initial admission. Once the API has returned the exact
+operation, a later wake-notification failure resumes from an exact journal read;
+it still rejects any mismatched operation. If that recovery read is unavailable,
+the client returns `outcomeUnknown: true` with the exact operation id so the
+caller can reconcile without generating a second identity. The API also treats
+its post-dispatch journal refresh as best-effort and returns the already-admitted
+operation if that refresh is unavailable. The database serializes concurrent
+first submissions of one operation id, so identical races converge to one
+creation plus one replay rather than a unique-constraint failure. No response
+after operation creation triggers a catalog retry. While a journaled operation
+remains queued or running, the client periodically re-notifies the dispatcher
+with the same operation id. A live claim is not replayed; an expired claim is
+either reclaimed before execution or durably settled outcome-unknown after the
+execution marker. Public
+`CodemodeTransportError` identity and its `codemode_transport_error`
+compatibility code remain unchanged; the stable API detail is exposed as
+`remoteCode`.
+
 The bearer is reread for every request. Namespace paths are resolved against
 the signed catalog and never parsed into authority from flattened model names.
 For Browser/Computer work, the authored facade wraps those same atomic entries:
@@ -47,7 +73,21 @@ await app.getByRole("button", { name: "1" }).invoke();
 
 Both surfaces return the same durable tool receipts. Human approval, catalog
 generation, operation idempotency, and outcome-unknown behavior remain enforced
-by the shared attempt executor.
+by the shared attempt executor. Catalog, approval, authorization, input
+validation, and argument-sensitive connector-policy prepare complete before the
+durable execution-start marker. The prepared call performs connector begin at
+the executor boundary and completion afterward, so model MCP and Codemode share
+one lifecycle while invalid, blocked, Ask, or unavailable-policy calls settle
+before provider execution. Human-gated model calls additionally require the
+attempt host's exact approved SDK invocation context; calling the environment
+directly cannot bypass approval. The dispatcher keeps its claim alive during
+gateway preparation and reuses a deterministic durable tool-created event if a
+pre-execution claim is reclaimed.
+
+`CodemodeCallOptions.signal` cancels only the caller's HTTP/polling observation.
+It does not request server cancellation and cannot prove that an operation
+stopped. The attempt/turn lifecycle remains the only cancellation authority; a
+caller that aborts after submission must reconcile with the same operation id.
 
 Editable artifacts use the same path. The object remains in OpenGeni; files are
 only explicit import/export boundaries:

package/dist/declarations.d.ts

@@ -1,4 +1,5 @@
 import type { AttemptToolCatalog } from "@opengeni/contracts";
+import { jsonSchemaToTypeScript } from "@opengeni/tool-gateway";
 export type GenerateCodemodeDeclarationsOptions = {
     /** Package whose augmentable CodemodeGeneratedTools interface owns the namespace. */
     moduleSpecifier?: string;
@@ -8,5 +9,4 @@ export type GenerateCodemodeDeclarationsOptions = {
  * Types improve authoring only; runtime catalog validation remains authoritative.
  */
 export declare function generateCodemodeDeclarations(catalog: AttemptToolCatalog, options?: GenerateCodemodeDeclarationsOptions): string;
-/** Honest JSON-Schema-to-TypeScript projection used by declaration generation. */
-export declare function jsonSchemaToTypeScript(schema: unknown): string;
+export { jsonSchemaToTypeScript };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { type ValidateFunction } from "ajv";
-import { type AttemptToolCall as AttemptToolCallValue, type AttemptToolCaller, type AttemptToolCatalog as AttemptToolCatalogValue, type AttemptToolCatalogEntry as AttemptToolCatalogEntryValue, type AttemptToolIdentity, type AttemptToolResult as AttemptToolResultValue, type CodemodeDispatchAck as CodemodeDispatchAckValue, type CodemodeDispatchRequest as CodemodeDispatchRequestValue, type CodemodeOperation as CodemodeOperationValue } from "@opengeni/contracts";
+import { type AttemptToolCall as AttemptToolCallValue, AttemptToolCaller, type AttemptToolCatalog as AttemptToolCatalogValue, type AttemptToolCatalogEntry as AttemptToolCatalogEntryValue, type AttemptToolIdentity, type AttemptToolResult as AttemptToolResultValue, type CodemodeDispatchAck as CodemodeDispatchAckValue, type CodemodeDispatchRequest as CodemodeDispatchRequestValue, type CodemodeOperation as CodemodeOperationValue } from "@opengeni/contracts";
+import { ToolGateway, ToolGatewayApprovalRequiredError as AttemptToolApprovalRequiredError, ToolGatewayCatalogIntegrityError as AttemptToolCatalogIntegrityError, ToolGatewayCatalogStaleError as AttemptToolCatalogStaleError, ToolGatewayCatalogTooLargeError as AttemptToolCatalogTooLargeError, ToolGatewayInputValidationError as AttemptToolInputValidationError, ToolGatewayOutputValidationError as AttemptToolOutputValidationError, ToolGatewayPathCollisionError as AttemptToolPathCollisionError, ToolGatewayToolNotFoundError as AttemptToolNotFoundError, type PreparedToolGatewayCall, type ToolGatewayCallLifecycle } from "@opengeni/tool-gateway";
 export type { AttemptToolCatalog, AttemptToolCatalogEntry } from "@opengeni/contracts";
 export type AttemptToolScope = Pick<AttemptToolCatalogValue, "accountId" | "workspaceId" | "sessionId" | "turnId" | "attemptId" | "executionGeneration">;
 export type AttemptToolExecutionContext = {
@@ -12,6 +12,8 @@ export type AttemptToolExecutionContext = {
 export type AttemptToolDefinition = Omit<AttemptToolCatalogEntryValue, "codemodePath"> & {
     /** Optional human-readable path. Unsafe/colliding segments are normalized. */
     codemodePath?: readonly string[];
+    /** In-process execution lifecycle shared by model MCP and Codemode. */
+    lifecycle?: ToolGatewayCallLifecycle;
     execute: (args: Record<string, unknown>, context: AttemptToolExecutionContext) => Promise<AttemptToolResultValue> | AttemptToolResultValue;
 };
 export type AttemptToolAuthorization = (input: {
@@ -24,6 +26,11 @@ export type CreateAttemptToolEnvironmentInput = {
     definitions: readonly AttemptToolDefinition[];
     createdAt?: Date;
     authorize?: AttemptToolAuthorization;
+    /** Host-only approval projection for one exact model invocation. */
+    confirmModelApproval?: (input: {
+        modelName: string;
+        subjectId: string;
+    }) => boolean;
 };
 export type ModelAttemptToolCall = {
     operationId?: string;
@@ -33,38 +40,20 @@ export type ModelAttemptToolCall = {
     transportMeta?: Record<string, unknown> | null;
     signal?: AbortSignal;
 };
-export declare class AttemptToolCatalogStaleError extends Error {
-    readonly code = "catalog_stale";
-    constructor();
-}
-export declare class AttemptToolNotFoundError extends Error {
-    readonly code = "tool_not_found";
-    constructor();
-}
-export declare class AttemptToolApprovalRequiredError extends Error {
-    readonly code = "approval_required";
-    constructor();
-}
-export declare class AttemptToolCatalogIntegrityError extends Error {
-    readonly code = "catalog_integrity_failed";
-    constructor();
-}
-export declare class AttemptToolCatalogTooLargeError extends Error {
-    readonly code = "catalog_too_large";
-    constructor();
-}
-export declare class AttemptToolInputValidationError extends Error {
-    readonly code = "invalid_tool_arguments";
-    constructor();
-}
-export declare class AttemptToolOutputValidationError extends Error {
-    readonly code = "invalid_tool_result";
-    constructor();
-}
+export { AttemptToolCatalogStaleError, AttemptToolNotFoundError, AttemptToolApprovalRequiredError, AttemptToolCatalogIntegrityError, AttemptToolCatalogTooLargeError, AttemptToolInputValidationError, AttemptToolOutputValidationError, AttemptToolPathCollisionError, };
 export declare class CodemodeTransportError extends Error {
     readonly status: number | null;
     readonly code = "codemode_transport_error";
-    constructor(message: string, status?: number | null);
+    readonly remoteCode: string | null;
+    readonly retryable: boolean | null;
+    readonly outcomeUnknown: boolean | null;
+    readonly details: Readonly<Record<string, unknown>> | null;
+    constructor(message: string, status?: number | null, options?: {
+        code?: string;
+        retryable?: boolean;
+        outcomeUnknown?: boolean;
+        details?: Readonly<Record<string, unknown>>;
+    });
 }
 export declare class CodemodeOperationError extends Error {
     readonly operation: CodemodeOperationValue;
@@ -82,6 +71,7 @@ export type CodemodeClientOptions = {
 };
 export type CodemodeCallOptions = {
     operationId?: string;
+    /** Stops client observation only; it never cancels an already-created server operation. */
     signal?: AbortSignal;
     timeoutMs?: number;
 };
@@ -118,6 +108,7 @@ export declare class CodemodeClient {
         signal?: AbortSignal;
     }): Promise<CodemodeTools>;
     call(identity: AttemptToolIdentity, argumentsValue?: Record<string, unknown>, options?: CodemodeCallOptions): Promise<AttemptToolResultValue>;
+    private callResolved;
     /** Resolve and call one exact generated namespace path without parsing a wire name. */
     callPath(path: readonly string[], argumentsValue?: Record<string, unknown>, options?: CodemodeCallOptions): Promise<AttemptToolResultValue>;
     /** Return structured content when the catalog declares it; otherwise retain the full MCP result. */
@@ -127,22 +118,18 @@ export declare class CodemodeClient {
     private request;
 }
 export declare function compileCodemodeTools(catalog: AttemptToolCatalogValue, client: CodemodeClient): CodemodeTools;
-type CompiledDefinition = {
-    entry: AttemptToolCatalogEntryValue;
-    execute: AttemptToolDefinition["execute"];
-    validateInput: ValidateFunction<unknown>;
-    validateOutput: ValidateFunction<unknown> | null;
-};
 export declare class AttemptToolEnvironment {
-    private readonly authorize;
     readonly catalog: AttemptToolCatalogValue;
-    private readonly byIdentity;
-    private readonly byModelName;
-    constructor(catalog: AttemptToolCatalogValue, definitions: readonly CompiledDefinition[], authorize: AttemptToolAuthorization | undefined);
+    private readonly gateway;
+    constructor(catalog: AttemptToolCatalogValue, gateway: ToolGateway);
     call(input: AttemptToolCallValue, context?: {
         transportMeta?: Record<string, unknown> | null;
         signal?: AbortSignal;
     }): Promise<AttemptToolResultValue>;
+    prepareCall(input: AttemptToolCallValue, context?: {
+        transportMeta?: Record<string, unknown> | null;
+        signal?: AbortSignal;
+    }): Promise<PreparedToolGatewayCall>;
     callModel(input: ModelAttemptToolCall): Promise<AttemptToolResultValue>;
 }
 export declare function createAttemptToolEnvironment(input: CreateAttemptToolEnvironmentInput): AttemptToolEnvironment;
@@ -159,3 +146,4 @@ export * from "./interaction.js";
 export * from "./artifacts.js";
 export * from "./structured.js";
 export * from "./declarations.js";
+export * from "./site.js";