@hypercli.com/sdk 0.9.1

package/dist/keys.js

@@ -0,0 +1,145 @@
+/**
+ * API Keys management
+ */
+import { getApiUrl } from './config.js';
+import { HTTPClient } from './http.js';
+export const API_KEY_BASELINE_FAMILIES = [
+    { key: 'api', label: 'API Keys', allowed: ['none', 'self', '*'] },
+    { key: 'user', label: 'Profile', allowed: ['none', 'self', '*'] },
+    { key: 'jobs', label: 'Jobs', allowed: ['none', 'self', '*'] },
+    { key: 'renders', label: 'Renders', allowed: ['none', 'self', '*'] },
+    { key: 'files', label: 'Files', allowed: ['none', 'self', '*'] },
+    { key: 'agents', label: 'Agents', allowed: ['none', 'self', '*'] },
+    { key: 'models', label: 'Models', allowed: ['none', '*'] },
+    { key: 'voice', label: 'Voice', allowed: ['none', '*'] },
+    { key: 'flow', label: 'Flows', allowed: ['none', '*'] },
+];
+function asRecord(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    return {};
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value !== 'string')
+            continue;
+        const trimmed = value.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return null;
+}
+function firstTimestamp(...values) {
+    for (const value of values) {
+        if (typeof value === 'string') {
+            const trimmed = value.trim();
+            if (!trimmed)
+                continue;
+            const numeric = Number(trimmed);
+            if (!Number.isFinite(numeric))
+                return trimmed;
+            const milliseconds = Math.abs(numeric) < 1_000_000_000_000 ? numeric * 1000 : numeric;
+            const timestamp = new Date(milliseconds);
+            if (Number.isFinite(timestamp.getTime()))
+                return timestamp.toISOString();
+        }
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            const milliseconds = Math.abs(value) < 1_000_000_000_000 ? value * 1000 : value;
+            const timestamp = new Date(milliseconds);
+            if (Number.isFinite(timestamp.getTime()))
+                return timestamp.toISOString();
+        }
+    }
+    return null;
+}
+function apiKeyFromDict(data) {
+    const record = asRecord(data);
+    return {
+        keyId: firstString(record.key_id, record.keyId, record.id) || '',
+        name: firstString(record.name) || '',
+        tags: Array.isArray(record.tags) ? record.tags.filter((tag) => typeof tag === 'string') : [],
+        apiKey: firstString(record.api_key, record.apiKey, record.key, record.secret, record.token, record.value),
+        apiKeyPreview: firstString(record.api_key_preview, record.apiKeyPreview, record.preview, record.masked_key, record.maskedKey),
+        last4: firstString(record.last4, record.last_4),
+        isActive: record.is_active === false || record.isActive === false || record.active === false ? false : true,
+        createdAt: firstTimestamp(record.created_at, record.createdAt) || '',
+        lastUsedAt: firstTimestamp(record.last_used_at, record.lastUsedAt),
+        expiresAt: firstTimestamp(record.expires_at, record.expiresAt),
+        capabilities: Array.isArray(record.capabilities)
+            ? record.capabilities.filter((capability) => typeof capability === 'string')
+            : undefined,
+    };
+}
+export class KeysAPI {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Create a new API key
+     */
+    async create(name = 'default', tags, options = {}) {
+        const payload = { name };
+        if (tags !== undefined) {
+            payload.tags = tags;
+        }
+        if (options.duration !== undefined) {
+            payload.duration = options.duration;
+        }
+        if (options.expiresAt !== undefined) {
+            payload.expires_at = options.expiresAt;
+        }
+        const data = await this.http.post('/api/keys', payload);
+        return apiKeyFromDict(data);
+    }
+    /**
+     * List all API keys (masked)
+     */
+    async list() {
+        const data = await this.http.get('/api/keys');
+        return (data || []).map(apiKeyFromDict);
+    }
+    /**
+     * Get a specific API key (masked)
+     */
+    async get(keyId) {
+        const data = await this.http.get(`/api/keys/${keyId}`);
+        return apiKeyFromDict(data);
+    }
+    /**
+     * Deactivate an API key (irreversible)
+     */
+    async disable(keyId) {
+        return await this.http.delete(`/api/keys/${keyId}`);
+    }
+    /**
+     * Rename an API key
+     */
+    async rename(keyId, name) {
+        const data = await this.http.patch(`/api/keys/${keyId}`, { name });
+        return apiKeyFromDict(data);
+    }
+}
+/**
+ * Issue a scoped API key for the user represented by an app JWT.
+ *
+ * The JWT authenticates only this key-creation request. Use the returned
+ * `apiKey` for subsequent SDK operations.
+ */
+export async function issueApiKeyFromJwt(jwt, options) {
+    const token = jwt.trim();
+    if (!token) {
+        throw new Error('JWT required');
+    }
+    const http = new HTTPClient(options.apiUrl ?? getApiUrl(), token, options.timeout ?? 30000);
+    const issued = await new KeysAPI(http).create(options.name ?? 'default', options.tags, {
+        duration: options.duration,
+        expiresAt: options.expiresAt,
+    });
+    if (!issued.apiKey) {
+        throw new Error('API key issue response did not include the key secret');
+    }
+    return issued;
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"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"}

package/dist/logs.d.ts

@@ -0,0 +1,54 @@
+import type { HyperCLI } from './client.js';
+/**
+ * Fetch logs via REST API (one-time call)
+ */
+export declare function fetchLogs(client: HyperCLI, jobId: string, tail?: number): Promise<string[]>;
+/**
+ * Async log streamer - WebSocket streaming with optional initial fetch
+ */
+export declare class LogStream {
+    private client;
+    private jobId;
+    private jobKey?;
+    private fetchInitial;
+    private maxInitialLines;
+    private maxBuffer;
+    private ws;
+    private buffer;
+    private initialFetched;
+    private connected;
+    private closed;
+    constructor(client: HyperCLI, jobId: string, jobKey?: string | undefined, fetchInitial?: boolean, maxInitialLines?: number, maxBuffer?: number);
+    get status(): 'disconnected' | 'connecting' | 'connected' | 'closed';
+    /**
+     * Connect to log stream. Returns initial logs if fetchInitial=true.
+     */
+    connect(): Promise<string[]>;
+    /**
+     * Close the WebSocket connection
+     */
+    close(): Promise<void>;
+    /**
+     * Get current buffer contents (bounded, oldest may be dropped)
+     */
+    getBuffer(): string[];
+    /**
+     * Clear the buffer
+     */
+    clearBuffer(): void;
+    /**
+     * Async iterate over NEW log lines from WebSocket
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<string>;
+}
+/**
+ * Stream logs until job reaches a terminal state
+ */
+export declare function streamLogs(client: HyperCLI, jobId: string, onLine: (line: string) => void, options?: {
+    untilState?: Set<string>;
+    pollStateInterval?: number;
+    fetchInitial?: boolean;
+    fetchFinal?: boolean;
+    maxInitialLines?: number;
+}): Promise<void>;
+//# sourceMappingURL=logs.d.ts.map

package/dist/logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.d.ts","sourceRoot":"","sources":["../src/logs.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAO5C;;GAEG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CAcnB;AAED;;GAEG;AACH,qBAAa,SAAS;IAQlB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,MAAM,CAAC;IACf,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,eAAe;IACvB,OAAO,CAAC,SAAS;IAZnB,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;gBAGb,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,YAAY,GAAE,OAAc,EAC5B,eAAe,GAAE,MAAkC,EACnD,SAAS,GAAE,MAA2B;IAGhD,IAAI,MAAM,IAAI,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAKnE;IAED;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAsDlC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;OAEG;IACH,SAAS,IAAI,MAAM,EAAE;IAIrB;;OAEG;IACH,WAAW,IAAI,IAAI;IAInB;;OAEG;IACI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,MAAM,CAAC;CAqExD;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC9B,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GACA,OAAO,CAAC,IAAI,CAAC,CAoEf"}

package/dist/logs.js

@@ -0,0 +1,256 @@
+/**
+ * Async log streaming for jobs using WebSocket
+ */
+import WebSocket from 'ws';
+import { getWsUrl, WS_LOGS_PATH } from './config.js';
+// Default limits to prevent memory blowup
+const DEFAULT_MAX_INITIAL_LINES = 1000;
+const DEFAULT_MAX_BUFFER = 5000;
+/**
+ * Fetch logs via REST API (one-time call)
+ */
+export async function fetchLogs(client, jobId, tail) {
+    try {
+        const logs = await client.jobs.logs(jobId);
+        if (!logs) {
+            return [];
+        }
+        const lines = logs.trim().split('\n');
+        if (tail && lines.length > tail) {
+            return lines.slice(-tail);
+        }
+        return lines;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Async log streamer - WebSocket streaming with optional initial fetch
+ */
+export class LogStream {
+    client;
+    jobId;
+    jobKey;
+    fetchInitial;
+    maxInitialLines;
+    maxBuffer;
+    ws = null;
+    buffer = [];
+    initialFetched = false;
+    connected = false;
+    closed = false;
+    constructor(client, jobId, jobKey, fetchInitial = true, maxInitialLines = DEFAULT_MAX_INITIAL_LINES, maxBuffer = DEFAULT_MAX_BUFFER) {
+        this.client = client;
+        this.jobId = jobId;
+        this.jobKey = jobKey;
+        this.fetchInitial = fetchInitial;
+        this.maxInitialLines = maxInitialLines;
+        this.maxBuffer = maxBuffer;
+    }
+    get status() {
+        if (this.closed)
+            return 'closed';
+        if (this.connected)
+            return 'connected';
+        if (this.ws)
+            return 'connecting';
+        return 'disconnected';
+    }
+    /**
+     * Connect to log stream. Returns initial logs if fetchInitial=true.
+     */
+    async connect() {
+        if (this.closed) {
+            throw new Error('LogStream is closed');
+        }
+        const initialLines = [];
+        // Fetch initial logs ONCE (bounded)
+        if (this.fetchInitial && !this.initialFetched) {
+            const logs = await fetchLogs(this.client, this.jobId, this.maxInitialLines);
+            for (const line of logs) {
+                this.buffer.push(line);
+                if (this.buffer.length > this.maxBuffer) {
+                    this.buffer.shift(); // Remove oldest
+                }
+            }
+            initialLines.push(...logs);
+            this.initialFetched = true;
+        }
+        // Get job_key if not provided
+        if (!this.jobKey) {
+            const job = await this.client.jobs.get(this.jobId);
+            this.jobKey = job.jobKey;
+        }
+        // Connect WebSocket
+        if (this.jobKey && !this.ws) {
+            const wsUrl = getWsUrl();
+            const fullUrl = `${wsUrl}${WS_LOGS_PATH}/${this.jobKey}`;
+            await new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => {
+                    reject(new Error('WebSocket connection timeout'));
+                }, 30000);
+                this.ws = new WebSocket(fullUrl);
+                this.ws.on('open', () => {
+                    clearTimeout(timeout);
+                    this.connected = true;
+                    resolve();
+                });
+                this.ws.on('error', (error) => {
+                    clearTimeout(timeout);
+                    reject(error);
+                });
+            });
+        }
+        return initialLines;
+    }
+    /**
+     * Close the WebSocket connection
+     */
+    async close() {
+        this.closed = true;
+        this.connected = false;
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+    /**
+     * Get current buffer contents (bounded, oldest may be dropped)
+     */
+    getBuffer() {
+        return [...this.buffer];
+    }
+    /**
+     * Clear the buffer
+     */
+    clearBuffer() {
+        this.buffer = [];
+    }
+    /**
+     * Async iterate over NEW log lines from WebSocket
+     */
+    async *[Symbol.asyncIterator]() {
+        if (!this.ws) {
+            throw new Error('Not connected. Call connect() first.');
+        }
+        const messageQueue = [];
+        let resolveNext = null;
+        let rejectNext = null;
+        this.ws.on('message', (data) => {
+            if (this.closed)
+                return;
+            try {
+                const message = JSON.parse(data.toString());
+                if (message.event === 'log' && message.log) {
+                    for (const line of message.log.split('\n')) {
+                        if (line) {
+                            this.buffer.push(line);
+                            if (this.buffer.length > this.maxBuffer) {
+                                this.buffer.shift();
+                            }
+                            if (resolveNext) {
+                                resolveNext({ done: false, value: line });
+                                resolveNext = null;
+                            }
+                            else {
+                                messageQueue.push(line);
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                // Ignore JSON parse errors
+            }
+        });
+        this.ws.on('close', () => {
+            this.connected = false;
+            if (resolveNext) {
+                resolveNext({ done: true, value: undefined });
+                resolveNext = null;
+            }
+        });
+        this.ws.on('error', (error) => {
+            if (rejectNext) {
+                rejectNext(error);
+                rejectNext = null;
+            }
+        });
+        while (!this.closed) {
+            if (messageQueue.length > 0) {
+                yield messageQueue.shift();
+            }
+            else {
+                // Wait for next message
+                const result = await new Promise((resolve, reject) => {
+                    resolveNext = resolve;
+                    rejectNext = reject;
+                });
+                if (result.done) {
+                    break;
+                }
+                yield result.value;
+            }
+        }
+    }
+}
+/**
+ * Stream logs until job reaches a terminal state
+ */
+export async function streamLogs(client, jobId, onLine, options) {
+    const { untilState = new Set(['succeeded', 'failed', 'canceled', 'terminated']), pollStateInterval = 2000, fetchInitial = true, fetchFinal = true, maxInitialLines = DEFAULT_MAX_INITIAL_LINES, } = options || {};
+    let job = await client.jobs.get(jobId);
+    // Wait for job to be assigned/running
+    while (job.state === 'pending' || job.state === 'queued') {
+        await new Promise(resolve => setTimeout(resolve, pollStateInterval));
+        job = await client.jobs.get(jobId);
+    }
+    // Check for immediate terminal state
+    if (untilState.has(job.state)) {
+        if (fetchFinal) {
+            const logs = await fetchLogs(client, jobId, maxInitialLines);
+            for (const line of logs) {
+                onLine(line);
+            }
+        }
+        return;
+    }
+    // Fetch initial logs if running
+    if (fetchInitial && job.state === 'running') {
+        const logs = await fetchLogs(client, jobId, maxInitialLines);
+        for (const line of logs) {
+            onLine(line);
+        }
+    }
+    // Connect WebSocket
+    if (job.jobKey) {
+        const stream = new LogStream(client, jobId, job.jobKey, false);
+        await stream.connect();
+        try {
+            // Stream logs while checking job state periodically
+            const checkInterval = setInterval(async () => {
+                job = await client.jobs.get(jobId);
+                if (untilState.has(job.state)) {
+                    await stream.close();
+                }
+            }, pollStateInterval);
+            for await (const line of stream) {
+                onLine(line);
+            }
+            clearInterval(checkInterval);
+        }
+        finally {
+            await stream.close();
+        }
+    }
+    // Fetch final logs
+    if (fetchFinal) {
+        await new Promise(resolve => setTimeout(resolve, 500));
+        const logs = await fetchLogs(client, jobId, maxInitialLines);
+        for (const line of logs) {
+            onLine(line);
+        }
+    }
+}
+//# sourceMappingURL=logs.js.map

package/dist/logs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.js","sourceRoot":"","sources":["../src/logs.ts"],"names":[],"mappings":"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"}

package/dist/managed-context.d.ts

@@ -0,0 +1,20 @@
+import type { Agent, Deployments } from './agents.js';
+export declare const MANAGED_CONTEXT_PATHS: readonly [".hypercli/USER.md", ".hypercli/SOUL.md"];
+export interface ManagedContext {
+    /** Missing means leave the file alone; null projects an explicitly empty profile. */
+    profile?: string | null;
+    description?: string | null;
+}
+export interface ManagedContextFileResult {
+    path: typeof MANAGED_CONTEXT_PATHS[number];
+    status: 'written' | 'unchanged' | 'preserved' | 'skipped' | 'failed';
+    detail?: string;
+}
+/**
+ * Explicit, one-way projection. The caller must supply the authenticated account UUID.
+ * Owner deployments use Reef or the native runner's retained assignment root. No start, policy change,
+ * directory cleanup, or import back into account metadata occurs. Each PUT is atomic;
+ * the file API has no compare-and-swap or multi-file transaction.
+ */
+export declare function projectManagedContext(deployments: Deployments, agent: Agent, ownerUserId: string, context: ManagedContext): Promise<ManagedContextFileResult[]>;
+//# sourceMappingURL=managed-context.d.ts.map

package/dist/managed-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-context.d.ts","sourceRoot":"","sources":["../src/managed-context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtD,eAAO,MAAM,qBAAqB,qDAAsD,CAAC;AACzF,MAAM,WAAW,cAAc;IAC7B,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AACD,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,OAAO,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,wBAAwB,EAAE,CAAC,CA+DrC"}

package/dist/managed-context.js

@@ -0,0 +1,95 @@
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex } from '@noble/hashes/utils';
+import { APIError } from './errors.js';
+export const MANAGED_CONTEXT_PATHS = ['.hypercli/USER.md', '.hypercli/SOUL.md'];
+function digest(text) {
+    return bytesToHex(sha256(new TextEncoder().encode(text)));
+}
+function projection(text) {
+    return `<!-- hypercli-projection sha256:${digest(text)} -->\n${text}`;
+}
+function isUneditedProjection(text) {
+    const match = /^<!-- hypercli-projection sha256:([a-f0-9]{64}) -->\n/.exec(text);
+    return !!match && digest(text.slice(match[0].length)) === match[1];
+}
+/**
+ * Explicit, one-way projection. The caller must supply the authenticated account UUID.
+ * Owner deployments use Reef or the native runner's retained assignment root. No start, policy change,
+ * directory cleanup, or import back into account metadata occurs. Each PUT is atomic;
+ * the file API has no compare-and-swap or multi-file transaction.
+ */
+export async function projectManagedContext(deployments, agent, ownerUserId, context) {
+    const values = [context.profile, context.description];
+    const results = [];
+    let unavailable;
+    if (!ownerUserId || agent.userId !== ownerUserId)
+        unavailable = 'Only the owning account can project personal context.';
+    else if (!['STOPPED', 'RUNNING', 'STARTING', 'STOPPING'].includes(String(agent.state).toUpperCase())) {
+        unavailable = `Files are unavailable in ${agent.state}; retry when storage is ready.`;
+    }
+    if (!unavailable) {
+        try {
+            await deployments.waitForFileApiReady(agent, { timeoutMs: 10_000 });
+        }
+        catch (error) {
+            unavailable = String(error);
+        }
+    }
+    for (const [index, path] of MANAGED_CONTEXT_PATHS.entries()) {
+        const value = values[index];
+        if (value === undefined) {
+            results.push({ path, status: 'skipped', detail: 'No server value has been set.' });
+            continue;
+        }
+        if (unavailable) {
+            results.push({ path, status: 'skipped', detail: unavailable });
+            continue;
+        }
+        const include = agent.launchConfig?.sync_include;
+        const exclude = agent.launchConfig?.sync_exclude;
+        // Do not guess glob semantics or mutate an immutable retained-storage policy.
+        if (!agent.runner && ((Array.isArray(include) && !include.includes(path) && !include.includes('.hypercli'))
+            || (Array.isArray(exclude) && exclude.length > 0))) {
+            results.push({ path, status: 'skipped', detail: 'Persistence policy does not explicitly cover this file. Review the retained-storage policy; existing agents cannot change it after first launch.' });
+            continue;
+        }
+        try {
+            if (value !== null && (typeof value !== 'string' || [...value].length > 32768))
+                throw new Error('Markdown must be at most 32768 characters.');
+            const text = projection(value ?? '');
+            let current;
+            if (agent.runner) {
+                try {
+                    current = await deployments.fileRead(agent, path);
+                }
+                catch (error) {
+                    if (!(error instanceof APIError) || error.statusCode !== 404 || error.detail !== 'Runner file not_found')
+                        throw error;
+                }
+            }
+            else {
+                const root = await deployments.filesList(agent, '');
+                const directory = root.find((entry) => entry.name === '.hypercli');
+                if (directory && directory.type !== 'directory')
+                    throw new Error('.hypercli is not a directory.');
+                const files = directory ? await deployments.filesList(agent, '.hypercli') : [];
+                const exists = files.some((entry) => entry.name === path.split('/')[1]);
+                current = exists ? await deployments.fileRead(agent, path) : undefined;
+            }
+            if (current === text)
+                results.push({ path, status: 'unchanged' });
+            else if (current !== undefined && !isUneditedProjection(current)) {
+                results.push({ path, status: 'preserved', detail: 'Existing user content preserved. Move it aside explicitly before projecting.' });
+            }
+            else {
+                await deployments.fileWrite(agent, path, text);
+                results.push({ path, status: 'written' });
+            }
+        }
+        catch (error) {
+            results.push({ path, status: 'failed', detail: String(error) });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=managed-context.js.map

package/dist/managed-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-context.js","sourceRoot":"","sources":["../src/managed-context.ts"],"names":[],"mappings":"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"}

package/dist/mcp.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@agentclientprotocol/sdk';
+/** Assemble explicit platform/integration and external selections for the
+ * existing launch `env` option. The host owns merging/conflict handling; the
+ * runtime owns transport support. No credentials or process env are discovered.
+ */
+export declare function buildAdditionalMcpEnv(...groups: readonly McpServer[][]): Record<string, string>;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE/F"}

package/dist/mcp.js

@@ -0,0 +1,8 @@
+/** Assemble explicit platform/integration and external selections for the
+ * existing launch `env` option. The host owns merging/conflict handling; the
+ * runtime owns transport support. No credentials or process env are discovered.
+ */
+export function buildAdditionalMcpEnv(...groups) {
+    return { HYPER_ADDITIONAL_MCP_SERVERS: JSON.stringify(groups.flat()) };
+}
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAG,MAA8B;IACrE,OAAO,EAAE,4BAA4B,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;AACzE,CAAC"}