@opengeni/codemode 0.2.2 → 0.4.1

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.1",
   "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;