@the-open-engine/zeroshot 6.27.0 → 6.28.0

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.27.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,14 +40,17 @@
     "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 && npm run typecheck:hosted-session",
+    "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: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",
@@ -55,7 +58,7 @@
     "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 tests/hosted-session/coordinator.test.js",
-    "test:cluster-package": "npm run build:agent-cli-provider && npm run build:cluster && node --test tests/cluster/package.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",
@@ -77,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": [
@@ -167,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": {

package/src/target/credential-lock.ts

@@ -0,0 +1,35 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+// @ts-expect-error no declaration file for proper-lockfile
+import lockfile from 'proper-lockfile';
+
+const LOCK_STALE_MS = 10_000;
+const LOCK_RETRIES = 100;
+const LOCK_RETRY_MIN_TIMEOUT_MS = 50;
+const LOCK_RETRY_MAX_TIMEOUT_MS = 5_000;
+
+export async function acquireTargetLock(targetId: string): Promise<() => Promise<void>> {
+  const lockDir = path.join(os.homedir(), '.zeroshot');
+  await fs.mkdir(lockDir, { recursive: true });
+
+  const lockTarget = path.join(lockDir, `target-${targetId}.lock`);
+  try {
+    await fs.writeFile(lockTarget, '', { flag: 'wx' });
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+  }
+
+  const release = await lockfile.lock(lockTarget, {
+    stale: LOCK_STALE_MS,
+    retries: {
+      retries: LOCK_RETRIES,
+      minTimeout: LOCK_RETRY_MIN_TIMEOUT_MS,
+      maxTimeout: LOCK_RETRY_MAX_TIMEOUT_MS,
+    },
+  });
+
+  return async () => {
+    await release();
+  };
+}

package/src/target/credential-store.ts

@@ -0,0 +1,107 @@
+export class CredentialStoreUnavailableError extends Error {
+  constructor(message?: string) {
+    super(
+      message ??
+        'OS secure store unavailable. Install libsecret (Linux), or run on macOS/Windows. No plaintext fallback.',
+    );
+    this.name = 'CredentialStoreUnavailableError';
+  }
+}
+
+export interface TargetCredentialStore {
+  get(service: string, account: string): Promise<string | null>;
+  set(service: string, account: string, token: string): Promise<void>;
+  delete(service: string, account: string): Promise<void>;
+}
+
+export function targetServiceKey(targetId: string): string {
+  return `zeroshot-target-${targetId}`;
+}
+
+export const TARGET_ACCOUNT = 'refresh-token';
+
+export class KeyringCredentialStore implements TargetCredentialStore {
+  private readonly Entry: new (service: string, account: string) => {
+    getPassword(): string;
+    setPassword(password: string): void;
+    deletePassword(): void;
+  };
+
+  private constructor(
+    Entry: new (service: string, account: string) => {
+      getPassword(): string;
+      setPassword(password: string): void;
+      deletePassword(): void;
+    },
+  ) {
+    this.Entry = Entry;
+  }
+
+  static async create(): Promise<KeyringCredentialStore> {
+    let keyringModule: { Entry: new (service: string, account: string) => {
+      getPassword(): string;
+      setPassword(password: string): void;
+      deletePassword(): void;
+    } };
+    try {
+      keyringModule = await import('@napi-rs/keyring') as typeof keyringModule;
+    } catch {
+      throw new CredentialStoreUnavailableError();
+    }
+    if (!keyringModule.Entry) {
+      throw new CredentialStoreUnavailableError();
+    }
+    return new KeyringCredentialStore(keyringModule.Entry);
+  }
+
+  async get(service: string, account: string): Promise<string | null> {
+    try {
+      const entry = new this.Entry(service, account);
+      return entry.getPassword();
+    } catch {
+      return null;
+    }
+  }
+
+  async set(service: string, account: string, token: string): Promise<void> {
+    const entry = new this.Entry(service, account);
+    entry.setPassword(token);
+  }
+
+  async delete(service: string, account: string): Promise<void> {
+    try {
+      const entry = new this.Entry(service, account);
+      entry.deletePassword();
+    } catch {
+      // Already deleted or not present
+    }
+  }
+}
+
+export class FakeCredentialStore implements TargetCredentialStore {
+  private readonly store = new Map<string, string>();
+
+  private key(service: string, account: string): string {
+    return `${service}::${account}`;
+  }
+
+  async get(service: string, account: string): Promise<string | null> {
+    return this.store.get(this.key(service, account)) ?? null;
+  }
+
+  async set(service: string, account: string, token: string): Promise<void> {
+    this.store.set(this.key(service, account), token);
+  }
+
+  async delete(service: string, account: string): Promise<void> {
+    this.store.delete(this.key(service, account));
+  }
+
+  has(service: string, account: string): boolean {
+    return this.store.has(this.key(service, account));
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+}