@opengeni/codemode 0.2.2 → 0.4.2

package/dist/interaction.d.ts

@@ -1,4 +1,4 @@
-import type { AttachedBrowserDevice, BrowserAction, BrowserActionReceipt, BrowserDiagnosticBatch, BrowserDiagnosticKind, BrowserIdentity, BrowserIdentityListResponse, BrowserIdentityMutationResponse, BrowserLocator, BrowserObservation, BrowserRevisionListResponse, BrowserSession, BrowserSessionMutationResponse, BrowserTargetListResponse, ComputerAction, ComputerActionReceipt, ComputerLocator, ComputerObservation, ComputerSession, ComputerSessionMutationResponse, ComputerTargetListResponse, InteractionPlacement, PublishBrowserRevisionResponse } from "@opengeni/contracts";
+import type { AttachedBrowserDevice, AuthRun, AuthRunListResponse, AuthRunMutationResponse, BrowserAction, BrowserActionReceipt, BrowserClipboard, BrowserDiagnosticBatch, BrowserDiagnosticKind, BrowserIdentity, BrowserIdentityListResponse, BrowserIdentityMutationResponse, BrowserLocator, BrowserObservation, BrowserPermission, BrowserPermissionSetting, BrowserRevisionListResponse, BrowserSession, BrowserSessionMutationResponse, BrowserTargetListResponse, ComputerAction, ComputerActionReceipt, ComputerClipboard, ComputerLocator, ComputerObservation, ComputerSession, ComputerSessionMutationResponse, ComputerTargetListResponse, ExternalAuthRunRequest, ExternalAuthRunResponse, InteractionPlacement, ProtectedAuthFillRequest, ProtectedAuthFillResponse, PublishBrowserRevisionResponse, ReportAuthRunRequest, RequestHumanInteractionToolInput, RequestHumanInteractionToolOutput, SiteAuthConnection, SiteAuthConnectionListResponse, StartAuthRunRequest, UpdateBrowserIdentityRequest, VerifyAuthRunRequest } from "@opengeni/contracts";
 import type { CodemodeCallOptions, CodemodeClient } from "./index.js";
 import { type CodemodeClientProvider } from "./environment.js";
 import { CodemodeArtifactCollection } from "./artifacts.js";
@@ -45,12 +45,14 @@ export declare class OpenGeniCodemode {
     readonly browsers: CodemodeBrowserCollection;
     readonly computers: CodemodeComputerCollection;
     readonly artifacts: CodemodeArtifactCollection;
+    readonly auth: CodemodeAuth;
     constructor(client?: CodemodeClient | CodemodeClientProvider);
     discover(options?: {
         includeTerminal?: boolean | undefined;
         includeArchivedIdentities?: boolean | undefined;
         includeDisconnectedDevices?: boolean | undefined;
     }, callOptions?: CodemodeCallOptions): Promise<InteractionDiscovery>;
+    requestHuman(request: RequestHumanInteractionToolInput, callOptions?: CodemodeCallOptions): Promise<RequestHumanInteractionToolOutput>;
 }
 export declare class CodemodeBrowserCollection {
     readonly client: CodemodeClientProvider;
@@ -71,11 +73,14 @@ export declare class CodemodeBrowserIdentityCollection {
     get(identityId: string, callOptions?: CodemodeCallOptions): Promise<BrowserIdentity>;
     create(name: string, callOptions?: CodemodeCallOptions): Promise<BrowserIdentityMutationResponse>;
     revisions(identityId: string, callOptions?: CodemodeCallOptions): Promise<BrowserRevisionListResponse>;
+    update(identityId: string, update: Omit<UpdateBrowserIdentityRequest, "operationId">, callOptions?: CodemodeCallOptions): Promise<BrowserIdentityMutationResponse>;
 }
 export declare class CodemodeBrowser {
     private readonly client;
     readonly id: string;
     readonly tabs: CodemodeBrowserTabCollection;
+    readonly auth: CodemodeBrowserAuth;
+    readonly clipboard: CodemodeBrowserClipboard;
     constructor(client: CodemodeClientProvider, id: string);
     refresh(callOptions?: CodemodeCallOptions): Promise<BrowserSession>;
     observe(targetId?: string, callOptions?: CodemodeCallOptions): Promise<BrowserObservation>;
@@ -97,6 +102,30 @@ export declare class CodemodeBrowser {
     end(callOptions?: CodemodeCallOptions): Promise<BrowserSessionMutationResponse>;
     private lifecycle;
 }
+export declare class CodemodeBrowserClipboard {
+    private readonly client;
+    private readonly browserSessionId;
+    private readonly tabs;
+    constructor(client: CodemodeClientProvider, browserSessionId: string, tabs: CodemodeBrowserTabCollection);
+    read(callOptions?: CodemodeCallOptions): Promise<BrowserClipboard>;
+    write(text: string, options?: BrowserActionFences & {
+        targetId?: string | undefined;
+    }, callOptions?: CodemodeCallOptions): Promise<BrowserActionReceipt>;
+    clear(options?: BrowserActionFences & {
+        targetId?: string | undefined;
+    }, callOptions?: CodemodeCallOptions): Promise<BrowserActionReceipt>;
+    copy(options?: BrowserActionFences & {
+        targetId?: string | undefined;
+        locator?: BrowserLocator | undefined;
+        content?: "selection" | "value" | "text" | undefined;
+    }, callOptions?: CodemodeCallOptions): Promise<BrowserActionReceipt>;
+    paste(options?: BrowserActionFences & {
+        targetId?: string | undefined;
+        locator?: BrowserLocator | undefined;
+        text?: string | undefined;
+    }, callOptions?: CodemodeCallOptions): Promise<BrowserActionReceipt>;
+    private act;
+}
 export declare class CodemodeBrowserTabCollection {
     private readonly client;
     private readonly browserSessionId;
@@ -207,6 +236,12 @@ export declare class CodemodeBrowserTab {
             details?: Record<string, import("zod").JSONType> | undefined;
         } | null;
     }>;
+    setPermission(permission: BrowserPermission, setting: BrowserPermissionSetting, fences?: BrowserActionFences, callOptions?: CodemodeCallOptions): Promise<BrowserActionReceipt>;
+    requestHuman(reason: string, options?: {
+        kind?: "manual_login" | "mfa" | "external_action" | "confirmation" | "other";
+        authRunId?: string | undefined;
+        expiresInSeconds?: number | undefined;
+    }, callOptions?: CodemodeCallOptions): Promise<RequestHumanInteractionToolOutput>;
     getByRole(role: string, options?: {
         name?: string;
         exact?: boolean;
@@ -953,6 +988,43 @@ export declare class CodemodeBrowserLocator {
         } | null;
     }>;
 }
+export declare class CodemodeAuth {
+    private readonly client;
+    constructor(client: CodemodeClientProvider);
+    listConnections(options?: {
+        includeArchived?: boolean | undefined;
+    }, callOptions?: CodemodeCallOptions): Promise<SiteAuthConnectionListResponse>;
+    getConnection(siteAuthConnectionId: string, callOptions?: CodemodeCallOptions): Promise<SiteAuthConnection>;
+    listRuns(options?: {
+        browserSessionId?: string | undefined;
+        siteAuthConnectionId?: string | undefined;
+        includeSettled?: boolean | undefined;
+    }, callOptions?: CodemodeCallOptions): Promise<AuthRunListResponse>;
+    getRun(authRunId: string, callOptions?: CodemodeCallOptions): Promise<AuthRun>;
+    use(browserSessionId: string, authRunId: string): CodemodeAuthRun;
+}
+export declare class CodemodeBrowserAuth {
+    private readonly client;
+    private readonly browserSessionId;
+    constructor(client: CodemodeClientProvider, browserSessionId: string);
+    listRuns(options?: {
+        siteAuthConnectionId?: string | undefined;
+        includeSettled?: boolean | undefined;
+    }, callOptions?: CodemodeCallOptions): Promise<AuthRunListResponse>;
+    start(request: Omit<StartAuthRunRequest, "operationId">, callOptions?: CodemodeCallOptions): Promise<CodemodeAuthRun>;
+    use(authRunId: string): CodemodeAuthRun;
+}
+export declare class CodemodeAuthRun {
+    private readonly client;
+    readonly browserSessionId: string;
+    readonly id: string;
+    constructor(client: CodemodeClientProvider, browserSessionId: string, id: string);
+    get(callOptions?: CodemodeCallOptions): Promise<AuthRun>;
+    report(request: Omit<ReportAuthRunRequest, "operationId">, callOptions?: CodemodeCallOptions): Promise<AuthRunMutationResponse>;
+    protectedFill(request: Omit<ProtectedAuthFillRequest, "operationId">, callOptions?: CodemodeCallOptions): Promise<ProtectedAuthFillResponse>;
+    advanceExternal(request: Omit<ExternalAuthRunRequest, "operationId">, callOptions?: CodemodeCallOptions): Promise<ExternalAuthRunResponse>;
+    verify(request: Omit<VerifyAuthRunRequest, "operationId">, callOptions?: CodemodeCallOptions): Promise<AuthRunMutationResponse>;
+}
 export declare class CodemodeComputerCollection {
     private readonly client;
     constructor(client: CodemodeClientProvider);
@@ -967,6 +1039,7 @@ export declare class CodemodeComputer {
     readonly id: string;
     readonly targets: CodemodeComputerTargetCollection;
     readonly apps: CodemodeComputerTargetCollection;
+    readonly clipboard: CodemodeComputerClipboard;
     constructor(client: CodemodeClientProvider, id: string);
     refresh(callOptions?: CodemodeCallOptions): Promise<ComputerSession>;
     observe(targetId?: string, callOptions?: CodemodeCallOptions): Promise<ComputerObservation>;
@@ -996,6 +1069,26 @@ export declare class CodemodeComputer {
     }>;
     end(callOptions?: CodemodeCallOptions): Promise<ComputerSessionMutationResponse>;
 }
+export declare class CodemodeComputerClipboard {
+    private readonly client;
+    readonly computerSessionId: string;
+    private readonly targets;
+    constructor(client: CodemodeClientProvider, computerSessionId: string, targets: CodemodeComputerTargetCollection);
+    read(callOptions?: CodemodeCallOptions): Promise<ComputerClipboard>;
+    write(text: string, options?: {
+        targetId?: string | undefined;
+    }, callOptions?: CodemodeCallOptions): Promise<ComputerActionReceipt>;
+    clear(options?: {
+        targetId?: string | undefined;
+    }, callOptions?: CodemodeCallOptions): Promise<ComputerActionReceipt>;
+    copy(options?: {
+        targetId?: string | undefined;
+    }, callOptions?: CodemodeCallOptions): Promise<ComputerActionReceipt>;
+    paste(options?: {
+        targetId?: string | undefined;
+    }, callOptions?: CodemodeCallOptions): Promise<ComputerActionReceipt>;
+    private mutate;
+}
 export declare class CodemodeComputerTargetCollection {
     private readonly client;
     private readonly computerSessionId;
@@ -1004,6 +1097,7 @@ export declare class CodemodeComputerTargetCollection {
     use(targetId: string): CodemodeComputerTarget;
     focused(callOptions?: CodemodeCallOptions): Promise<CodemodeComputerTarget>;
     resolveId(targetId: string | undefined, callOptions: CodemodeCallOptions): Promise<string>;
+    resolveSeatId(targetId: string | undefined, callOptions: CodemodeCallOptions): Promise<string>;
 }
 export declare class CodemodeComputerTarget {
     private readonly client;
@@ -1012,6 +1106,10 @@ export declare class CodemodeComputerTarget {
     constructor(client: CodemodeClientProvider, computerSessionId: string, id: string);
     observe(callOptions?: CodemodeCallOptions): Promise<ComputerObservation>;
     act(action: ComputerAction, fences?: ComputerActionFences, callOptions?: CodemodeCallOptions): Promise<ComputerActionReceipt>;
+    requestHuman(reason: string, options?: {
+        kind?: "manual_login" | "mfa" | "external_action" | "confirmation" | "other";
+        expiresInSeconds?: number | undefined;
+    }, callOptions?: CodemodeCallOptions): Promise<RequestHumanInteractionToolOutput>;
     getByRole(role: string, options?: {
         name?: string;
         exact?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/codemode",
-  "version": "0.2.2",
+  "version": "0.4.2",
   "description": "Attempt-frozen programmatic tool catalog and execution authority for OpenGeni.",
   "license": "Apache-2.0",
   "repository": {
@@ -34,7 +34,7 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/contracts": "^0.44.1",
+    "@opengeni/contracts": "^0.50.0",
     "ajv": "^8.20.0"
   },
   "engines": {

package/src/environment.ts

@@ -3,9 +3,13 @@ import { CodemodeClient, type CodemodeCallOptions, type CodemodeToolFunction } f
 
 export const CODEMODE_ENVIRONMENT = {
   url: "OPENGENI_CODEMODE_URL",
+  token: "OPENGENI_CODEMODE_TOKEN",
   tokenFile: "OPENGENI_CODEMODE_TOKEN_FILE",
 } as const;
 
+/** Minimal environment shape; public declarations must not require `@types/node`. */
+export type CodemodeEnvironment = Readonly<Record<string, string | undefined>>;
+
 export type CodemodeClientProvider = () => CodemodeClient | Promise<CodemodeClient>;
 
 /** A lazy catalog path. Every nested property remains callable at runtime. */
@@ -29,17 +33,25 @@ let cachedEnvironmentClient: { key: string; client: CodemodeClient } | null = nu
  * The bearer file is reread for every HTTP request so worker renewal is live.
  */
 export function environmentCodemodeClient(
-  environment: NodeJS.ProcessEnv = process.env,
+  environment: CodemodeEnvironment = process.env,
 ): CodemodeClient {
   const baseUrl = requiredEnvironment(environment, CODEMODE_ENVIRONMENT.url);
-  const tokenFile = requiredEnvironment(environment, CODEMODE_ENVIRONMENT.tokenFile);
-  const key = `${baseUrl}\u0000${tokenFile}`;
+  const directTokenConfigured = environment[CODEMODE_ENVIRONMENT.token] !== undefined;
+  const tokenFile = directTokenConfigured
+    ? undefined
+    : requiredEnvironment(environment, CODEMODE_ENVIRONMENT.tokenFile);
+  // Never place bearer bytes in the cache identity. The callback rereads the
+  // selected source for every request: managed token-file renewal is live, and
+  // a Connected Machine child never leaves its direct bearer in module state.
+  const key = `${baseUrl}\u0000${directTokenConfigured ? "direct" : `file:${tokenFile}`}`;
   if (environment === process.env && cachedEnvironmentClient?.key === key) {
     return cachedEnvironmentClient.client;
   }
   const client = new CodemodeClient({
     baseUrl,
-    token: async () => await readBearerFile(tokenFile),
+    token: directTokenConfigured
+      ? async () => requiredEnvironment(environment, CODEMODE_ENVIRONMENT.token)
+      : async () => await readBearerFile(tokenFile!),
   });
   if (environment === process.env) cachedEnvironmentClient = { key, client };
   return client;
@@ -94,7 +106,7 @@ async function readBearerFile(path: string): Promise<string> {
   return token;
 }
 
-function requiredEnvironment(environment: NodeJS.ProcessEnv, name: string): string {
+function requiredEnvironment(environment: CodemodeEnvironment, name: string): string {
   const value = environment[name]?.trim();
   if (!value) throw new Error(`${name} is required`);
   return value;

package/src/index.ts

@@ -364,7 +364,12 @@ export class CodemodeClient {
       method: "POST",
       ...(signal ? { signal } : {}),
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ operationId, catalogDigest, identity, arguments: argumentsValue }),
+      body: JSON.stringify({
+        operationId,
+        catalogDigest,
+        identity,
+        arguments: argumentsValue,
+      }),
     });
     return CodemodeCallSubmission.parse(await response.json()).operation;
   }
@@ -390,7 +395,9 @@ export class CodemodeClient {
     if (!response.ok) {
       let message = `Codemode request failed with HTTP ${response.status}`;
       try {
-        const payload = (await response.json()) as { error?: { message?: unknown } };
+        const payload = (await response.json()) as {
+          error?: { message?: unknown };
+        };
         if (typeof payload.error?.message === "string") message = payload.error.message;
       } catch {
         // The status is sufficient; never echo an unbounded provider body.
@@ -453,7 +460,10 @@ export class AttemptToolEnvironment {
 
   async call(
     input: AttemptToolCallValue,
-    context: { transportMeta?: Record<string, unknown> | null; signal?: AbortSignal } = {},
+    context: {
+      transportMeta?: Record<string, unknown> | null;
+      signal?: AbortSignal;
+    } = {},
   ): Promise<AttemptToolResultValue> {
     const call = AttemptToolCall.parse(input);
     if (call.catalogDigest !== this.catalog.digest) {
@@ -598,6 +608,15 @@ function assertCatalogSize(catalog: AttemptToolCatalogValue): void {
 
 type SchemaCompiler = { compile(schema: object): ValidateFunction<unknown> };
 
+// Validator compilation is structural and independent of attempt identity,
+// executable closures, credentials, and authorization. Reuse only exact
+// content-addressed validators; the attempt environment and catalog remain
+// freshly bound and digested on every execution. The hard cap prevents an
+// untrusted MCP schema stream from turning this process cache into a memory
+// sink.
+const COMPILED_CATALOG_SCHEMA_CACHE_MAX_ENTRIES = 512;
+const compiledCatalogSchemaCache = new Map<string, ValidateFunction<unknown>>();
+
 function createSchemaValidators(): {
   draft7: SchemaCompiler;
   draft2019: SchemaCompiler;
@@ -622,9 +641,31 @@ function compileCatalogSchema(
   schema: AttemptToolCatalogEntryValue["inputSchema"],
 ): ValidateFunction<unknown> {
   const dialect = typeof schema.$schema === "string" ? schema.$schema : "";
-  if (dialect.includes("2020-12")) return validators.draft2020.compile(schema);
-  if (dialect.includes("2019-09")) return validators.draft2019.compile(schema);
-  return validators.draft7.compile(schema);
+  const family = dialect.includes("2020-12")
+    ? "2020-12"
+    : dialect.includes("2019-09")
+      ? "2019-09"
+      : "draft7";
+  const cacheKey = `${family}:${digestCanonicalJson(schema)}`;
+  const cached = compiledCatalogSchemaCache.get(cacheKey);
+  if (cached) {
+    compiledCatalogSchemaCache.delete(cacheKey);
+    compiledCatalogSchemaCache.set(cacheKey, cached);
+    return cached;
+  }
+  const compiled =
+    family === "2020-12"
+      ? validators.draft2020.compile(schema)
+      : family === "2019-09"
+        ? validators.draft2019.compile(schema)
+        : validators.draft7.compile(schema);
+  while (compiledCatalogSchemaCache.size >= COMPILED_CATALOG_SCHEMA_CACHE_MAX_ENTRIES) {
+    const oldest = compiledCatalogSchemaCache.keys().next().value;
+    if (oldest === undefined) break;
+    compiledCatalogSchemaCache.delete(oldest);
+  }
+  compiledCatalogSchemaCache.set(cacheKey, compiled);
+  return compiled;
 }
 
 function allocateCodemodePaths(definitions: readonly AttemptToolDefinition[]): string[][] {