@the-open-engine/zeroshot 6.26.0 → 6.28.0

package/lib/target/discovery.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TargetDiscoveryError = void 0;
+exports.discoverTargetSessionEndpoints = discoverTargetSessionEndpoints;
+const DISCOVERY_PATH = '/.well-known/openengine-hosted-target';
+const MAX_DISCOVERY_BYTES = 64 * 1024;
+class TargetDiscoveryError extends Error {
+    constructor(message) {
+        super(`Target discovery failed: ${message}`);
+        this.name = 'TargetDiscoveryError';
+    }
+}
+exports.TargetDiscoveryError = TargetDiscoveryError;
+function record(value, field) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TargetDiscoveryError(`${field} must be an object`);
+    }
+    return value;
+}
+function stringField(source, field) {
+    const value = source[field];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new TargetDiscoveryError(`${field} must be a non-empty string`);
+    }
+    return value;
+}
+function safeEndpoint(value, field, serviceOrigin) {
+    if (typeof value !== 'string') {
+        throw new TargetDiscoveryError(`${field} must be an absolute URL`);
+    }
+    let endpoint;
+    try {
+        endpoint = new URL(value);
+    }
+    catch {
+        throw new TargetDiscoveryError(`${field} must be an absolute URL`);
+    }
+    if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+        throw new TargetDiscoveryError(`${field} contains forbidden URL components`);
+    }
+    if (endpoint.origin !== serviceOrigin) {
+        throw new TargetDiscoveryError(`${field} must remain on the target origin`);
+    }
+    return endpoint.href;
+}
+async function readBoundedJson(response) {
+    const declaredLength = response.headers.get('content-length');
+    if (declaredLength !== null && Number(declaredLength) > MAX_DISCOVERY_BYTES) {
+        throw new TargetDiscoveryError('response exceeds the size limit');
+    }
+    if (!response.body)
+        return response.json();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > MAX_DISCOVERY_BYTES) {
+            await reader.cancel();
+            throw new TargetDiscoveryError('response exceeds the size limit');
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        throw new TargetDiscoveryError('response is not valid JSON');
+    }
+}
+async function fetchDocument(http, url) {
+    const response = await http.fetch(url, {
+        method: 'GET',
+        headers: { Accept: 'application/json' },
+        redirect: 'error',
+    });
+    if (!response.ok) {
+        throw new TargetDiscoveryError(`request failed with status ${response.status}`);
+    }
+    return record(await readBoundedJson(response), 'response');
+}
+async function discoverTargetSessionEndpoints(targetUrl, http) {
+    const target = new URL(targetUrl);
+    const discovery = await fetchDocument(http, new URL(DISCOVERY_PATH, target).href);
+    if (discovery.kind !== 'openengine.hosted-target/v1') {
+        throw new TargetDiscoveryError('unsupported hosted-target version');
+    }
+    if (discovery.organization_binding !== 'device_approval') {
+        throw new TargetDiscoveryError('unsupported organization binding');
+    }
+    const oauth = record(discovery.oauth, 'oauth');
+    const metadataUrl = safeEndpoint(oauth.metadata_url, 'oauth.metadata_url', target.origin);
+    const deviceEndpoint = safeEndpoint(oauth.device_authorization_endpoint, 'oauth.device_authorization_endpoint', target.origin);
+    const tokenEndpoint = safeEndpoint(oauth.token_endpoint, 'oauth.token_endpoint', target.origin);
+    const clientId = stringField(oauth, 'client_id');
+    const metadata = await fetchDocument(http, metadataUrl);
+    const metadataDeviceEndpoint = safeEndpoint(metadata.device_authorization_endpoint, 'device_authorization_endpoint', target.origin);
+    const metadataTokenEndpoint = safeEndpoint(metadata.token_endpoint, 'token_endpoint', target.origin);
+    if (metadataDeviceEndpoint !== deviceEndpoint || metadataTokenEndpoint !== tokenEndpoint) {
+        throw new TargetDiscoveryError('OAuth metadata does not match hosted-target discovery');
+    }
+    const revocationEndpoint = metadata.revocation_endpoint === undefined
+        ? undefined
+        : safeEndpoint(metadata.revocation_endpoint, 'revocation_endpoint', target.origin);
+    return {
+        deviceAuthorizationEndpoint: deviceEndpoint,
+        tokenEndpoint,
+        ...(revocationEndpoint === undefined ? {} : { revocationEndpoint }),
+        clientId,
+    };
+}

package/lib/target/index.d.ts

@@ -0,0 +1,6 @@
+export { CredentialStoreUnavailableError, KeyringCredentialStore, FakeCredentialStore, targetServiceKey, TARGET_ACCOUNT, type TargetCredentialStore, } from './credential-store.ts';
+export { acquireTargetLock } from './credential-lock.ts';
+export { requestDeviceCode, pollForToken, DeviceFlowDeniedError, DeviceFlowExpiredError, UnboundSessionError, type DeviceCodeResponse, type TokenResponse, type HttpTransport, type Clock, } from './device-flow.ts';
+export { addTarget, removeTarget, getTarget, listTargets, updateTargetOrganization, validateTargetName, normalizeAndValidateUrl, TargetNameInvalidError, TargetNameExistsError, TargetNotFoundError, TargetUrlInvalidError, type TargetRecord, type SettingsPort, } from './target-registry.ts';
+export { targetLogin, refreshAccessToken, getAccessTokenProvider, revokeAndCleanup, LoginRequiredError, type BrowserOpener, type TargetSessionDeps, type TargetAccessTokenProvider, } from './target-session.ts';
+export { discoverTargetSessionEndpoints, TargetDiscoveryError, type TargetSessionEndpoints, } from './discovery.ts';

package/lib/target/index.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TargetDiscoveryError = exports.discoverTargetSessionEndpoints = exports.LoginRequiredError = exports.revokeAndCleanup = exports.getAccessTokenProvider = exports.refreshAccessToken = exports.targetLogin = exports.TargetUrlInvalidError = exports.TargetNotFoundError = exports.TargetNameExistsError = exports.TargetNameInvalidError = exports.normalizeAndValidateUrl = exports.validateTargetName = exports.updateTargetOrganization = exports.listTargets = exports.getTarget = exports.removeTarget = exports.addTarget = exports.UnboundSessionError = exports.DeviceFlowExpiredError = exports.DeviceFlowDeniedError = exports.pollForToken = exports.requestDeviceCode = exports.acquireTargetLock = exports.TARGET_ACCOUNT = exports.targetServiceKey = exports.FakeCredentialStore = exports.KeyringCredentialStore = exports.CredentialStoreUnavailableError = void 0;
+var credential_store_ts_1 = require("./credential-store.js");
+Object.defineProperty(exports, "CredentialStoreUnavailableError", { enumerable: true, get: function () { return credential_store_ts_1.CredentialStoreUnavailableError; } });
+Object.defineProperty(exports, "KeyringCredentialStore", { enumerable: true, get: function () { return credential_store_ts_1.KeyringCredentialStore; } });
+Object.defineProperty(exports, "FakeCredentialStore", { enumerable: true, get: function () { return credential_store_ts_1.FakeCredentialStore; } });
+Object.defineProperty(exports, "targetServiceKey", { enumerable: true, get: function () { return credential_store_ts_1.targetServiceKey; } });
+Object.defineProperty(exports, "TARGET_ACCOUNT", { enumerable: true, get: function () { return credential_store_ts_1.TARGET_ACCOUNT; } });
+var credential_lock_ts_1 = require("./credential-lock.js");
+Object.defineProperty(exports, "acquireTargetLock", { enumerable: true, get: function () { return credential_lock_ts_1.acquireTargetLock; } });
+var device_flow_ts_1 = require("./device-flow.js");
+Object.defineProperty(exports, "requestDeviceCode", { enumerable: true, get: function () { return device_flow_ts_1.requestDeviceCode; } });
+Object.defineProperty(exports, "pollForToken", { enumerable: true, get: function () { return device_flow_ts_1.pollForToken; } });
+Object.defineProperty(exports, "DeviceFlowDeniedError", { enumerable: true, get: function () { return device_flow_ts_1.DeviceFlowDeniedError; } });
+Object.defineProperty(exports, "DeviceFlowExpiredError", { enumerable: true, get: function () { return device_flow_ts_1.DeviceFlowExpiredError; } });
+Object.defineProperty(exports, "UnboundSessionError", { enumerable: true, get: function () { return device_flow_ts_1.UnboundSessionError; } });
+var target_registry_ts_1 = require("./target-registry.js");
+Object.defineProperty(exports, "addTarget", { enumerable: true, get: function () { return target_registry_ts_1.addTarget; } });
+Object.defineProperty(exports, "removeTarget", { enumerable: true, get: function () { return target_registry_ts_1.removeTarget; } });
+Object.defineProperty(exports, "getTarget", { enumerable: true, get: function () { return target_registry_ts_1.getTarget; } });
+Object.defineProperty(exports, "listTargets", { enumerable: true, get: function () { return target_registry_ts_1.listTargets; } });
+Object.defineProperty(exports, "updateTargetOrganization", { enumerable: true, get: function () { return target_registry_ts_1.updateTargetOrganization; } });
+Object.defineProperty(exports, "validateTargetName", { enumerable: true, get: function () { return target_registry_ts_1.validateTargetName; } });
+Object.defineProperty(exports, "normalizeAndValidateUrl", { enumerable: true, get: function () { return target_registry_ts_1.normalizeAndValidateUrl; } });
+Object.defineProperty(exports, "TargetNameInvalidError", { enumerable: true, get: function () { return target_registry_ts_1.TargetNameInvalidError; } });
+Object.defineProperty(exports, "TargetNameExistsError", { enumerable: true, get: function () { return target_registry_ts_1.TargetNameExistsError; } });
+Object.defineProperty(exports, "TargetNotFoundError", { enumerable: true, get: function () { return target_registry_ts_1.TargetNotFoundError; } });
+Object.defineProperty(exports, "TargetUrlInvalidError", { enumerable: true, get: function () { return target_registry_ts_1.TargetUrlInvalidError; } });
+var target_session_ts_1 = require("./target-session.js");
+Object.defineProperty(exports, "targetLogin", { enumerable: true, get: function () { return target_session_ts_1.targetLogin; } });
+Object.defineProperty(exports, "refreshAccessToken", { enumerable: true, get: function () { return target_session_ts_1.refreshAccessToken; } });
+Object.defineProperty(exports, "getAccessTokenProvider", { enumerable: true, get: function () { return target_session_ts_1.getAccessTokenProvider; } });
+Object.defineProperty(exports, "revokeAndCleanup", { enumerable: true, get: function () { return target_session_ts_1.revokeAndCleanup; } });
+Object.defineProperty(exports, "LoginRequiredError", { enumerable: true, get: function () { return target_session_ts_1.LoginRequiredError; } });
+var discovery_ts_1 = require("./discovery.js");
+Object.defineProperty(exports, "discoverTargetSessionEndpoints", { enumerable: true, get: function () { return discovery_ts_1.discoverTargetSessionEndpoints; } });
+Object.defineProperty(exports, "TargetDiscoveryError", { enumerable: true, get: function () { return discovery_ts_1.TargetDiscoveryError; } });

package/lib/target/target-registry.d.ts

@@ -0,0 +1,45 @@
+export interface TargetRecord {
+    readonly id: string;
+    readonly url: string;
+    readonly adapterVersion: string;
+    readonly deviceToken: string;
+    readonly organization?: {
+        readonly id: string;
+        readonly name: string;
+    };
+    readonly createdAt: string;
+}
+export declare class TargetNameInvalidError extends Error {
+    constructor(name: string);
+}
+export declare class TargetNameExistsError extends Error {
+    constructor(name: string);
+}
+export declare class TargetNotFoundError extends Error {
+    constructor(name: string);
+}
+export declare class TargetUrlInvalidError extends Error {
+    constructor(url: string, reason: string);
+}
+export declare function validateTargetName(name: string): void;
+export declare function normalizeAndValidateUrl(rawUrl: string): string;
+interface SettingsWithTargets {
+    _targets?: Record<string, TargetRecord>;
+    [key: string]: unknown;
+}
+export interface SettingsPort {
+    load(): SettingsWithTargets;
+    mutate(mutator: (settings: SettingsWithTargets) => void): void;
+}
+export declare function addTarget(name: string, rawUrl: string, settings: SettingsPort): TargetRecord;
+export declare function removeTarget(name: string, settings: SettingsPort): TargetRecord;
+export declare function getTarget(name: string, settings: SettingsPort): TargetRecord | null;
+export declare function listTargets(settings: SettingsPort): Array<{
+    name: string;
+    record: TargetRecord;
+}>;
+export declare function updateTargetOrganization(name: string, organization: {
+    id: string;
+    name: string;
+}, settings: SettingsPort): void;
+export {};

package/lib/target/target-registry.js

@@ -0,0 +1,132 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TargetUrlInvalidError = exports.TargetNotFoundError = exports.TargetNameExistsError = exports.TargetNameInvalidError = void 0;
+exports.validateTargetName = validateTargetName;
+exports.normalizeAndValidateUrl = normalizeAndValidateUrl;
+exports.addTarget = addTarget;
+exports.removeTarget = removeTarget;
+exports.getTarget = getTarget;
+exports.listTargets = listTargets;
+exports.updateTargetOrganization = updateTargetOrganization;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+class TargetNameInvalidError extends Error {
+    constructor(name) {
+        super(`Invalid target name "${name}". Must be 1-64 characters, alphanumeric and hyphens only.`);
+        this.name = 'TargetNameInvalidError';
+    }
+}
+exports.TargetNameInvalidError = TargetNameInvalidError;
+class TargetNameExistsError extends Error {
+    constructor(name) {
+        super(`Target "${name}" already exists. Remove it first or choose a different name.`);
+        this.name = 'TargetNameExistsError';
+    }
+}
+exports.TargetNameExistsError = TargetNameExistsError;
+class TargetNotFoundError extends Error {
+    constructor(name) {
+        super(`Target "${name}" not found.`);
+        this.name = 'TargetNotFoundError';
+    }
+}
+exports.TargetNotFoundError = TargetNotFoundError;
+class TargetUrlInvalidError extends Error {
+    constructor(url, reason) {
+        super(`Invalid target URL "${url}": ${reason}`);
+        this.name = 'TargetUrlInvalidError';
+    }
+}
+exports.TargetUrlInvalidError = TargetUrlInvalidError;
+const TARGET_NAME_PATTERN = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,62}[a-zA-Z0-9])?$/;
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+function validateTargetName(name) {
+    if (!TARGET_NAME_PATTERN.test(name) || name.length > 64) {
+        throw new TargetNameInvalidError(name);
+    }
+}
+function normalizeAndValidateUrl(rawUrl) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new TargetUrlInvalidError(rawUrl, 'not a valid URL');
+    }
+    if (parsed.username || parsed.password) {
+        throw new TargetUrlInvalidError(rawUrl, 'URL must not contain userinfo');
+    }
+    if (parsed.search || parsed.hash) {
+        throw new TargetUrlInvalidError(rawUrl, 'URL must not contain query or fragment');
+    }
+    const isLoopback = LOOPBACK_HOSTS.has(parsed.hostname);
+    if (parsed.protocol !== 'https:' && !isLoopback) {
+        throw new TargetUrlInvalidError(rawUrl, 'HTTPS required for non-loopback targets');
+    }
+    let normalized = `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+    if (normalized.endsWith('/') && normalized.length > 1) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
+function addTarget(name, rawUrl, settings) {
+    validateTargetName(name);
+    const url = normalizeAndValidateUrl(rawUrl);
+    const existing = settings.load();
+    if (existing._targets?.[name]) {
+        throw new TargetNameExistsError(name);
+    }
+    const record = {
+        id: node_crypto_1.default.randomUUID(),
+        url,
+        adapterVersion: 'v1',
+        deviceToken: node_crypto_1.default.randomUUID(),
+        createdAt: new Date().toISOString(),
+    };
+    settings.mutate((s) => {
+        if (!s._targets) {
+            s._targets = {};
+        }
+        s._targets[name] = record;
+    });
+    return record;
+}
+function removeTarget(name, settings) {
+    const existing = settings.load();
+    const record = existing._targets?.[name];
+    if (!record) {
+        throw new TargetNotFoundError(name);
+    }
+    settings.mutate((s) => {
+        if (s._targets) {
+            delete s._targets[name];
+        }
+    });
+    return record;
+}
+function getTarget(name, settings) {
+    const existing = settings.load();
+    return existing._targets?.[name] ?? null;
+}
+function listTargets(settings) {
+    const existing = settings.load();
+    const targets = existing._targets ?? {};
+    return Object.entries(targets).map(([name, record]) => ({ name, record }));
+}
+function updateTargetOrganization(name, organization, settings) {
+    const existing = settings.load();
+    if (!existing._targets?.[name]) {
+        throw new TargetNotFoundError(name);
+    }
+    settings.mutate((s) => {
+        const target = s._targets?.[name];
+        if (target) {
+            s._targets[name] = {
+                ...target,
+                organization,
+            };
+        }
+    });
+}

package/lib/target/target-session.d.ts

@@ -0,0 +1,39 @@
+import type { TargetCredentialStore } from './credential-store.ts';
+import type { TargetRecord, SettingsPort } from './target-registry.ts';
+import { type HttpTransport, type Clock } from './device-flow.ts';
+export declare class LoginRequiredError extends Error {
+    readonly targetName: string;
+    constructor(targetName: string);
+}
+export interface BrowserOpener {
+    open(url: string): Promise<void>;
+}
+export interface TargetSessionDeps {
+    readonly http: HttpTransport;
+    readonly clock: Clock;
+    readonly browserOpener: BrowserOpener;
+    readonly stderr: {
+        write(s: string): void;
+    };
+    readonly discoveryEndpoints: {
+        readonly deviceAuthorizationEndpoint: string;
+        readonly tokenEndpoint: string;
+        readonly revocationEndpoint?: string;
+        readonly clientId: string;
+    };
+}
+export declare function targetLogin(targetName: string, target: TargetRecord, credentialStore: TargetCredentialStore, acquireLock: () => Promise<() => Promise<void>>, settings: SettingsPort, deps: TargetSessionDeps): Promise<{
+    organization: {
+        id: string;
+        name: string;
+    };
+}>;
+export declare function refreshAccessToken(targetName: string, target: TargetRecord, credentialStore: TargetCredentialStore, acquireLock: () => Promise<() => Promise<void>>, deps: Pick<TargetSessionDeps, 'http' | 'discoveryEndpoints'>): Promise<{
+    accessToken: string;
+    expiresIn: number;
+}>;
+export interface TargetAccessTokenProvider {
+    getAccessToken(signal?: AbortSignal): Promise<string>;
+}
+export declare function getAccessTokenProvider(targetName: string, target: TargetRecord, credentialStore: TargetCredentialStore, acquireLock: () => Promise<() => Promise<void>>, deps: Pick<TargetSessionDeps, 'http' | 'discoveryEndpoints'>, clock?: Clock): TargetAccessTokenProvider;
+export declare function revokeAndCleanup(target: TargetRecord, credentialStore: TargetCredentialStore, acquireLock: () => Promise<() => Promise<void>>, deps: Pick<TargetSessionDeps, 'http' | 'discoveryEndpoints'>, force: boolean): Promise<void>;

package/lib/target/target-session.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoginRequiredError = void 0;
+exports.targetLogin = targetLogin;
+exports.refreshAccessToken = refreshAccessToken;
+exports.getAccessTokenProvider = getAccessTokenProvider;
+exports.revokeAndCleanup = revokeAndCleanup;
+const device_flow_ts_1 = require("./device-flow.js");
+const credential_store_ts_1 = require("./credential-store.js");
+const target_registry_ts_1 = require("./target-registry.js");
+class LoginRequiredError extends Error {
+    targetName;
+    constructor(targetName) {
+        super(`Login required. Run: zeroshot target login ${targetName}`);
+        this.name = 'LoginRequiredError';
+        this.targetName = targetName;
+    }
+}
+exports.LoginRequiredError = LoginRequiredError;
+async function targetLogin(targetName, target, credentialStore, acquireLock, settings, deps) {
+    const { http, clock, browserOpener, stderr, discoveryEndpoints } = deps;
+    const { deviceAuthorizationEndpoint, tokenEndpoint, clientId } = discoveryEndpoints;
+    const codeResponse = await (0, device_flow_ts_1.requestDeviceCode)(deviceAuthorizationEndpoint, clientId, http);
+    stderr.write(`\nOpen this URL to authorize:\n  ${codeResponse.verification_uri}\n\nEnter code: ${codeResponse.user_code}\n\n`);
+    if (codeResponse.verification_uri_complete) {
+        try {
+            await browserOpener.open(codeResponse.verification_uri_complete);
+        }
+        catch {
+            // Browser open is best-effort
+        }
+    }
+    const tokenResponse = await (0, device_flow_ts_1.pollForToken)(tokenEndpoint, clientId, codeResponse.device_code, codeResponse.interval, codeResponse.expires_in, http, clock);
+    if (!tokenResponse.organization) {
+        throw new device_flow_ts_1.UnboundSessionError(codeResponse.verification_uri);
+    }
+    const serviceKey = (0, credential_store_ts_1.targetServiceKey)(target.id);
+    const release = await acquireLock();
+    try {
+        await credentialStore.set(serviceKey, credential_store_ts_1.TARGET_ACCOUNT, tokenResponse.refresh_token);
+    }
+    finally {
+        await release();
+    }
+    (0, target_registry_ts_1.updateTargetOrganization)(targetName, tokenResponse.organization, settings);
+    return { organization: tokenResponse.organization };
+}
+async function refreshAccessToken(targetName, target, credentialStore, acquireLock, deps) {
+    const { http, discoveryEndpoints } = deps;
+    const { tokenEndpoint, revocationEndpoint, clientId } = discoveryEndpoints;
+    const serviceKey = (0, credential_store_ts_1.targetServiceKey)(target.id);
+    const release = await acquireLock();
+    try {
+        const currentRefreshToken = await credentialStore.get(serviceKey, credential_store_ts_1.TARGET_ACCOUNT);
+        if (!currentRefreshToken) {
+            throw new LoginRequiredError(targetName);
+        }
+        const body = new URLSearchParams({
+            grant_type: 'refresh_token',
+            refresh_token: currentRefreshToken,
+            client_id: clientId,
+        });
+        let tokenResponse;
+        const response = await http.fetch(tokenEndpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: body.toString(),
+            redirect: 'error',
+        });
+        if (!response.ok) {
+            const errorBody = (await response.json().catch(() => ({ error: 'unknown' })));
+            if (errorBody.error === 'invalid_grant') {
+                await credentialStore.delete(serviceKey, credential_store_ts_1.TARGET_ACCOUNT);
+                throw new LoginRequiredError(targetName);
+            }
+            throw new Error(`Token refresh failed (${response.status}): ${errorBody.error}`);
+        }
+        tokenResponse = (await response.json());
+        try {
+            await credentialStore.set(serviceKey, credential_store_ts_1.TARGET_ACCOUNT, tokenResponse.refresh_token);
+        }
+        catch {
+            await bestEffortRevoke(tokenResponse.refresh_token, revocationEndpoint, clientId, http);
+            await credentialStore.delete(serviceKey, credential_store_ts_1.TARGET_ACCOUNT);
+            throw new LoginRequiredError(targetName);
+        }
+        return { accessToken: tokenResponse.access_token, expiresIn: tokenResponse.expires_in };
+    }
+    finally {
+        await release();
+    }
+}
+async function bestEffortRevoke(token, revocationEndpoint, clientId, http) {
+    if (!revocationEndpoint)
+        return;
+    try {
+        const body = new URLSearchParams({
+            token,
+            client_id: clientId,
+            token_type_hint: 'refresh_token',
+        });
+        await http.fetch(revocationEndpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: body.toString(),
+            redirect: 'error',
+        });
+    }
+    catch {
+        // Best-effort
+    }
+}
+function getAccessTokenProvider(targetName, target, credentialStore, acquireLock, deps, clock = { now: () => Date.now() }) {
+    let cachedToken = null;
+    let expiresAt = 0;
+    return {
+        async getAccessToken(_signal) {
+            if (cachedToken && clock.now() < expiresAt - 30_000) {
+                return cachedToken;
+            }
+            const result = await refreshAccessToken(targetName, target, credentialStore, acquireLock, deps);
+            cachedToken = result.accessToken;
+            expiresAt = clock.now() + result.expiresIn * 1000;
+            return result.accessToken;
+        },
+    };
+}
+async function revokeAndCleanup(target, credentialStore, acquireLock, deps, force) {
+    const { http, discoveryEndpoints } = deps;
+    const { revocationEndpoint, clientId } = discoveryEndpoints;
+    const serviceKey = (0, credential_store_ts_1.targetServiceKey)(target.id);
+    const release = await acquireLock();
+    try {
+        const refreshToken = await credentialStore.get(serviceKey, credential_store_ts_1.TARGET_ACCOUNT);
+        if (refreshToken && revocationEndpoint) {
+            const body = new URLSearchParams({
+                token: refreshToken,
+                client_id: clientId,
+                token_type_hint: 'refresh_token',
+            });
+            try {
+                const response = await http.fetch(revocationEndpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                    body: body.toString(),
+                    redirect: 'error',
+                });
+                if (!response.ok && !force) {
+                    throw new Error(`Remote revocation failed (${response.status}). Use --force to remove anyway.`);
+                }
+            }
+            catch (err) {
+                if (!force)
+                    throw err;
+            }
+        }
+        await credentialStore.delete(serviceKey, credential_store_ts_1.TARGET_ACCOUNT);
+    }
+    finally {
+        await release();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-open-engine/zeroshot",
-  "version": "6.26.0",
+  "version": "6.28.0",
   "description": "Multi-agent orchestration engine for Claude, Codex, and Gemini",
   "main": "src/orchestrator.js",
   "bin": {
@@ -29,7 +29,7 @@
     ]
   },
   "scripts": {
-    "pretest": "npm run build:agent-cli-provider",
+    "pretest": "npm run build:agent-cli-provider && npm run build:target",
     "test": "node tests/run-tests.js",
     "test:unit": "node tests/run-tests.js",
     "test:e2e": "mocha 'tests/e2e/**/*.test.js' --timeout 120000",
@@ -40,21 +40,25 @@
     "test:coverage:report": "c8 --reporter=html npm run test:unit && echo 'Coverage report generated at coverage/index.html'",
     "postinstall": "node scripts/fix-node-pty-permissions.js && node scripts/check-path.js",
     "start": "node cli/index.js",
-    "typecheck": "tsc --noEmit && npm run typecheck:cluster && npm run typecheck:hosted-target",
+    "typecheck": "tsc --noEmit && npm run typecheck:cluster && npm run typecheck:hosted-target && npm run typecheck:hosted-session && npm run typecheck:target",
     "typecheck:agent-cli-provider": "tsc --project tsconfig.agent-cli-provider.json",
     "typecheck:hosted-target": "tsc --project tsconfig.hosted-target.json",
+    "typecheck:hosted-session": "tsc --project tsconfig.hosted-session.json",
     "test:hosted-target": "node --test tests/hosted-target/*.test.ts",
+    "test:target": "npm run build:agent-cli-provider && npm run build:target && node --test tests/target/*.test.ts",
+    "typecheck:target": "tsc --project tsconfig.target.json",
     "typecheck:cluster": "tsc --project tsconfig.cluster.json",
     "lint:agent-cli-provider": "eslint \"src/agent-cli-provider/**/*.ts\" \"tests/agent-cli-provider/**/*.ts\"",
     "build:agent-cli-provider": "tsc --project tsconfig.agent-cli-provider.build.json",
-    "build:cluster": "npm run protocol:generate && tsc --project tsconfig.cluster.cjs.json && tsc --project tsconfig.cluster.esm.json && node scripts/build-cluster.js",
+    "build:target": "tsc --project tsconfig.target.build.json",
+    "build:cluster": "npm run protocol:generate && tsc --project tsconfig.cluster.cjs.json && tsc --project tsconfig.cluster.esm.json && tsc --project tsconfig.hosted-session.cjs.json && tsc --project tsconfig.hosted-session.esm.json && node scripts/build-cluster.js",
     "test:agent-cli-provider": "node --test tests/agent-cli-provider/*.test.js",
     "test:omp": "npm run build:agent-cli-provider && node --test tests/agent-cli-provider/omp-*.test.js && node tests/run-tests.js tests/omp-rpc-watcher.test.js tests/omp-isolation-capability.test.js tests/omp-docker-auth.test.js tests/omp-docker-fresh-only.test.js",
     "test:providers:live": "npm run build:agent-cli-provider && node scripts/live-provider-smoke.js",
     "check:agent-cli-provider": "npm run check:agent-cli-provider:ci",
     "check:agent-cli-provider:ci": "npm run typecheck:agent-cli-provider && npm run lint:agent-cli-provider && npm run build:agent-cli-provider && npm run test:agent-cli-provider",
-    "test:cluster-client": "npm run build:cluster && node --test tests/cluster/client.test.js tests/cluster/parity.test.js tests/cluster/architecture.test.js tests/cluster/verifier-regressions.test.js tests/cluster/request-validation.test.js",
-    "test:cluster-package": "npm run build:cluster && node --test tests/cluster/package.test.js",
+    "test:cluster-client": "npm run build:cluster && node --test tests/cluster/client.test.js tests/cluster/parity.test.js tests/cluster/architecture.test.js tests/cluster/verifier-regressions.test.js tests/cluster/request-validation.test.js tests/hosted-session/coordinator.test.js",
+    "test:cluster-package": "npm run build:agent-cli-provider && npm run build:cluster && npm run build:target && node --test tests/cluster/package.test.js",
     "dev:link": "npm link",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -76,9 +80,9 @@
     "release:preflight": "node scripts/release-preflight.js",
     "release:recover": "node scripts/release-recovery.js",
     "release:assert-published": "node scripts/assert-release-published.js",
-    "prepack": "npm run build:cluster",
+    "prepack": "npm run build:cluster && npm run build:target",
     "prepublishOnly": "npm run lint && npm run typecheck && npm run check:agent-cli-provider:ci",
-    "prepare": "npm run build:agent-cli-provider && husky"
+    "prepare": "npm run build:agent-cli-provider && npm run build:target && husky"
   },
   "c8": {
     "reporter": [
@@ -132,6 +136,12 @@
       "require": "./lib/cluster/index.cjs",
       "default": "./lib/cluster/index.cjs"
     },
+    "./hosted-session": {
+      "types": "./lib/hosted-session/index.d.ts",
+      "import": "./lib/hosted-session/index.mjs",
+      "require": "./lib/hosted-session/index.cjs",
+      "default": "./lib/hosted-session/index.cjs"
+    },
     "./package.json": "./package.json",
     "./*": "./*"
   },
@@ -160,9 +170,11 @@
     "node-pty": "^1.1.0",
     "omelette": "^0.4.17",
     "pidusage": "^4.0.1",
+    "open": "^10.1.0",
     "proper-lockfile": "^4.1.2"
   },
   "optionalDependencies": {
+    "@napi-rs/keyring": "^1.1.6",
     "ws": "^8.18.3"
   },
   "devDependencies": {