@qvac/core 0.0.0 → 0.1.0

package/dist-lib/lib/oauth/spotify.js

@@ -0,0 +1,73 @@
+import { URLSearchParams } from 'url';
+import defaultFetch from '#fetch';
+import { runBrowserConnect } from "./browser-connect.js";
+import { oauthRedirectUri, tokenRequest } from "./common.js";
+import { resolveOAuthCredential } from "./resolve.js";
+export const SPOTIFY_CREDENTIAL_KEY = 'spotify_access_token';
+export const SPOTIFY_OAUTH_STATE_KEY = 'spotify_oauth';
+export const SPOTIFY_OAUTH_PORT = 18974;
+const REDIRECT_URI = oauthRedirectUri(SPOTIFY_OAUTH_PORT);
+const AUTH_URL = 'https://accounts.spotify.com/authorize';
+const TOKEN_URL = 'https://accounts.spotify.com/api/token';
+const SCOPES = [
+    'user-read-playback-state',
+    'user-modify-playback-state',
+    'user-read-currently-playing',
+    'playlist-read-private',
+    'playlist-read-collaborative',
+    'user-library-read',
+    'user-top-read',
+    'user-read-recently-played'
+];
+export function buildSpotifyAuthUrl(opts) {
+    const params = new URLSearchParams({
+        response_type: 'code',
+        client_id: opts.clientId,
+        redirect_uri: REDIRECT_URI,
+        scope: SCOPES.join(' '),
+        state: opts.state,
+        code_challenge: opts.challenge,
+        code_challenge_method: 'S256'
+    });
+    return `${AUTH_URL}?${params.toString()}`;
+}
+export async function exchangeSpotifyCode(opts) {
+    return tokenRequest(opts.fetch ?? defaultFetch, TOKEN_URL, new URLSearchParams({
+        grant_type: 'authorization_code',
+        code: opts.code,
+        redirect_uri: REDIRECT_URI,
+        client_id: opts.clientId,
+        code_verifier: opts.verifier
+    }), 'Spotify');
+}
+export async function refreshSpotifyToken(opts) {
+    const tokens = await tokenRequest(opts.fetch ?? defaultFetch, TOKEN_URL, new URLSearchParams({
+        grant_type: 'refresh_token',
+        refresh_token: opts.refreshToken,
+        client_id: opts.clientId
+    }), 'Spotify');
+    return { ...tokens, refreshToken: tokens.refreshToken ?? opts.refreshToken };
+}
+export async function connectSpotify(opts) {
+    return runBrowserConnect({
+        port: SPOTIFY_OAUTH_PORT,
+        timeoutMs: opts.timeoutMs,
+        openUrl: opts.openUrl,
+        buildAuthUrl: ({ state, challenge }) => buildSpotifyAuthUrl({ clientId: opts.clientId, state, challenge }),
+        exchange: ({ code, verifier }) => exchangeSpotifyCode({
+            clientId: opts.clientId,
+            code,
+            verifier,
+            fetch: opts.fetch
+        })
+    });
+}
+export async function resolveSpotifyCredential(opts) {
+    return resolveOAuthCredential({
+        ...opts,
+        credentialKey: SPOTIFY_CREDENTIAL_KEY,
+        stateKey: SPOTIFY_OAUTH_STATE_KEY,
+        requireClientSecret: false,
+        refresh: async ({ clientId, refreshToken, fetch }) => refreshSpotifyToken({ clientId, refreshToken, fetch })
+    });
+}

package/dist-lib/lib/oauth/token-exchange-core.d.ts

@@ -0,0 +1,6 @@
+import type { OAuthFetch, OAuthFlowDeps, OAuthProviderConfig, OAuthTokens } from './types.ts';
+export declare function exchangeCodeWithFetch(config: OAuthProviderConfig, clientId: string, redirectUri: string, code: string, verifier: string, deps: OAuthFlowDeps, fetchImpl: OAuthFetch): Promise<OAuthTokens>;
+export declare function refreshOAuthTokensWithFetch(config: OAuthProviderConfig, refreshToken: string, fetchImpl: OAuthFetch): Promise<OAuthTokens>;
+export declare function isTokenExpired(record: {
+    readonly expiresAt?: number;
+}, bufferMs?: number): boolean;

package/dist-lib/lib/oauth/token-exchange-core.js

@@ -0,0 +1,97 @@
+import * as z from 'zod';
+const TOKEN_REQUEST_TIMEOUT_MS = 30_000;
+const TokenResponseSchema = z.object({
+    access_token: z.string(),
+    token_type: z.string(),
+    expires_in: z.number().optional(),
+    refresh_token: z.string().optional(),
+    scope: z.string().optional()
+});
+const TokenErrorSchema = z.object({
+    error: z.string(),
+    error_description: z.string().optional()
+});
+function parseTokenResponse(raw) {
+    const failure = TokenErrorSchema.safeParse(raw);
+    if (failure.success) {
+        const detail = failure.data.error_description;
+        throw new Error(`Token endpoint returned an error: ${failure.data.error}${detail ? ` — ${detail}` : ''}`);
+    }
+    return TokenResponseSchema.parse(raw);
+}
+function applyClientSecret(config, body, headers) {
+    if (config.tokenAuth === 'secret-in-body') {
+        body.set('client_secret', config.clientSecret);
+    }
+    else if (config.tokenAuth === 'secret-in-basic') {
+        headers.Authorization = `Basic ${globalThis.btoa(`${config.clientId}:${config.clientSecret}`)}`;
+    }
+}
+function toTokens(raw, fallbackRefresh) {
+    return {
+        accessToken: raw.access_token,
+        refreshToken: raw.refresh_token ?? fallbackRefresh,
+        expiresAt: raw.expires_in ? Date.now() + raw.expires_in * 1000 : undefined,
+        scope: raw.scope
+    };
+}
+export async function exchangeCodeWithFetch(config, clientId, redirectUri, code, verifier, deps, fetchImpl) {
+    const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        code,
+        redirect_uri: redirectUri,
+        client_id: clientId,
+        code_verifier: verifier
+    });
+    const headers = {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json'
+    };
+    applyClientSecret(config, body, headers);
+    const response = await fetchImpl(config.tokenUrl, {
+        method: 'POST',
+        headers,
+        body: body.toString()
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        if (config.dynamicRegistration && /invalid_client/i.test(text)) {
+            await deps.clearClientId?.();
+        }
+        throw new Error(`Token exchange failed (${response.status}): ${text}`);
+    }
+    return toTokens(parseTokenResponse(await response.json()));
+}
+export async function refreshOAuthTokensWithFetch(config, refreshToken, fetchImpl) {
+    const body = new URLSearchParams({
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+        client_id: config.clientId
+    });
+    const headers = {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json'
+    };
+    applyClientSecret(config, body, headers);
+    const controller = new globalThis.AbortController();
+    const timeout = globalThis.setTimeout(() => controller.abort(new Error('OAuth token refresh timed out')), TOKEN_REQUEST_TIMEOUT_MS);
+    try {
+        const response = await fetchImpl(config.tokenUrl, {
+            method: 'POST',
+            headers,
+            body: body.toString(),
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(`Token refresh failed (${response.status}): ${text}`);
+        }
+        return toTokens(parseTokenResponse(await response.json()), refreshToken);
+    }
+    finally {
+        globalThis.clearTimeout(timeout);
+    }
+}
+export function isTokenExpired(record, bufferMs = 60_000) {
+    return typeof record.expiresAt === 'number' && Date.now() + bufferMs >= record.expiresAt;
+}

package/dist-lib/lib/oauth/token-exchange.d.ts

@@ -0,0 +1,5 @@
+import type { OAuthFlowDeps, OAuthProviderConfig, OAuthTokens } from './types.ts';
+import { isTokenExpired } from './token-exchange-core.ts';
+export declare function exchangeCode(config: OAuthProviderConfig, clientId: string, redirectUri: string, code: string, verifier: string, deps: OAuthFlowDeps): Promise<OAuthTokens>;
+export declare function refreshOAuthTokens(config: OAuthProviderConfig, refreshToken: string): Promise<OAuthTokens>;
+export { isTokenExpired };

package/dist-lib/lib/oauth/token-exchange.js

@@ -0,0 +1,9 @@
+import defaultFetch from '@qvac/core/oauth/runtime/fetch';
+import { exchangeCodeWithFetch, isTokenExpired, refreshOAuthTokensWithFetch } from "./token-exchange-core.js";
+export function exchangeCode(config, clientId, redirectUri, code, verifier, deps) {
+    return exchangeCodeWithFetch(config, clientId, redirectUri, code, verifier, deps, defaultFetch);
+}
+export function refreshOAuthTokens(config, refreshToken) {
+    return refreshOAuthTokensWithFetch(config, refreshToken, defaultFetch);
+}
+export { isTokenExpired };

package/dist-lib/lib/oauth/types.d.ts

@@ -0,0 +1,54 @@
+import type { OAuthRedirectFactory } from './redirect-types.ts';
+export type OAuthProvider = 'google' | 'spotify' | 'asana' | 'notion';
+export type OAuthTokens = {
+    readonly accessToken: string;
+    readonly refreshToken?: string;
+    readonly expiresAt?: number;
+    readonly scope?: string;
+};
+export type OAuthFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type OAuthRuntime = {
+    readonly fetch: OAuthFetch;
+    readonly randomBase64Url: (size: number) => string;
+    readonly sha256Base64Url: (value: string) => string | Promise<string>;
+};
+export type OAuthCredentials = {
+    readonly clientId: string;
+    readonly clientSecret?: string;
+};
+type OAuthProviderConfigBase = {
+    readonly clientId: string;
+    readonly authUrl: string;
+    readonly tokenUrl: string;
+    readonly scopes: ReadonlyArray<string>;
+    readonly credentialKey: string;
+    readonly port: number;
+    readonly extraAuthParams?: Readonly<Record<string, string>>;
+    readonly dynamicRegistration?: boolean;
+    readonly registrationEndpoint?: string;
+};
+export type OAuthFlowDeps = {
+    readonly openUrl?: (url: string) => Promise<void>;
+    readonly timeoutMs?: number;
+    readonly getClientId?: () => Promise<string | undefined>;
+    readonly saveClientId?: (clientId: string) => Promise<void>;
+    readonly clearClientId?: () => Promise<void>;
+    readonly createRedirect?: OAuthRedirectFactory;
+};
+export type PkceOnlyProviderConfig = OAuthProviderConfigBase & {
+    readonly tokenAuth: 'pkce-only';
+};
+export type SecretInBodyProviderConfig = OAuthProviderConfigBase & {
+    readonly tokenAuth: 'secret-in-body';
+    readonly clientSecret: string;
+};
+export type SecretInBasicProviderConfig = OAuthProviderConfigBase & {
+    readonly tokenAuth: 'secret-in-basic';
+    readonly clientSecret: string;
+};
+export type OAuthProviderConfig = PkceOnlyProviderConfig | SecretInBodyProviderConfig | SecretInBasicProviderConfig;
+export type OAuthFlowResult = {
+    readonly config: OAuthProviderConfig;
+    readonly tokens: OAuthTokens;
+};
+export {};

package/dist-lib/lib/oauth/types.js

@@ -0,0 +1 @@
+export {};

package/dist-lib/lib/oauth.client.d.ts

@@ -0,0 +1,5 @@
+export { createOAuthClient, isTokenExpired, type OAuthClient } from './oauth/client.ts';
+export { buildProviderConfig, providerRequiresSecret, providerSupportsDcr, providerSupportsSharedIosSession } from './oauth/providers.ts';
+export type { OAuthCallbackResult, OAuthRedirect, OAuthRedirectFactory } from './oauth/redirect-types.ts';
+export type { OAuthRuntimeFlowDeps } from './oauth/flow-core.ts';
+export type { OAuthCredentials, OAuthFetch, OAuthFlowDeps, OAuthFlowResult, OAuthProvider, OAuthProviderConfig, OAuthRuntime, OAuthTokens } from './oauth/types.ts';

package/dist-lib/lib/oauth.client.js

@@ -0,0 +1,2 @@
+export { createOAuthClient, isTokenExpired } from "./oauth/client.js";
+export { buildProviderConfig, providerRequiresSecret, providerSupportsDcr, providerSupportsSharedIosSession } from "./oauth/providers.js";

package/dist-lib/lib/oauth.d.ts

@@ -0,0 +1,14 @@
+export { createPkce, scopedKey, type ConfigEngine, type Fetch, type FetchResponse, type OAuthTokens } from './oauth/common.ts';
+export { waitForOAuthCallback } from './oauth/browser-connect.ts';
+export { buildGoogleAuthUrl, connectGoogle, exchangeGoogleCode, GOOGLE_OAUTH_PORT, refreshGoogleToken, resolveGoogleCredential, type GoogleTokens } from './oauth/google.ts';
+export { buildNotionAuthUrl, connectNotion, exchangeNotionCode, NOTION_MCP_CREDENTIAL_KEY, NOTION_OAUTH_PORT, NOTION_OAUTH_STATE_KEY, refreshNotionToken, registerNotionClient, resolveNotionCredential, type NotionTokens } from './oauth/notion.ts';
+export { buildAsanaAuthUrl, connectAsana, exchangeAsanaCode, ASANA_MCP_CREDENTIAL_KEY, ASANA_OAUTH_PORT, ASANA_OAUTH_STATE_KEY, refreshAsanaToken, resolveAsanaCredential, type AsanaTokens } from './oauth/asana.ts';
+export { buildSpotifyAuthUrl, connectSpotify, exchangeSpotifyCode, refreshSpotifyToken, resolveSpotifyCredential, SPOTIFY_CREDENTIAL_KEY, SPOTIFY_OAUTH_PORT, SPOTIFY_OAUTH_STATE_KEY, type SpotifyTokens } from './oauth/spotify.ts';
+export { cancelOAuthFlow, runOAuthFlow } from './oauth/flow.ts';
+export { defaultCredentialKeyFor, GMAIL_CREDENTIAL_KEY, GOOGLE_CALENDAR_CREDENTIAL_KEY, GOOGLE_CREDENTIAL_KEYS, GOOGLE_DOCS_CREDENTIAL_KEY, GOOGLE_DRIVE_CREDENTIAL_KEY, GOOGLE_SHEETS_CREDENTIAL_KEY, LEGACY_GOOGLE_CREDENTIAL_KEY, OAUTH_KEY_SPECS, oauthKeySpec, oauthStateKeyFor, type OAuthKeySpec } from './oauth/keys.ts';
+export { generatePkceChallenge, type PkceChallenge } from './oauth/pkce.ts';
+export { buildProviderConfig, providerRequiresSecret, providerSupportsDcr, providerSupportsSharedIosSession } from './oauth/providers.ts';
+export type { OAuthCallbackResult, OAuthRedirect, OAuthRedirectFactory } from './oauth/redirect-types.ts';
+export { registerOAuthClient, resolveDynamicClientId } from './oauth/register.ts';
+export { isTokenExpired, refreshOAuthTokens } from './oauth/token-exchange.ts';
+export type { OAuthCredentials, OAuthFlowDeps, OAuthFlowResult, OAuthProvider, OAuthProviderConfig } from './oauth/types.ts';

package/dist-lib/lib/oauth.js

@@ -0,0 +1,12 @@
+export { createPkce, scopedKey } from "./oauth/common.js";
+export { waitForOAuthCallback } from "./oauth/browser-connect.js";
+export { buildGoogleAuthUrl, connectGoogle, exchangeGoogleCode, GOOGLE_OAUTH_PORT, refreshGoogleToken, resolveGoogleCredential } from "./oauth/google.js";
+export { buildNotionAuthUrl, connectNotion, exchangeNotionCode, NOTION_MCP_CREDENTIAL_KEY, NOTION_OAUTH_PORT, NOTION_OAUTH_STATE_KEY, refreshNotionToken, registerNotionClient, resolveNotionCredential } from "./oauth/notion.js";
+export { buildAsanaAuthUrl, connectAsana, exchangeAsanaCode, ASANA_MCP_CREDENTIAL_KEY, ASANA_OAUTH_PORT, ASANA_OAUTH_STATE_KEY, refreshAsanaToken, resolveAsanaCredential } from "./oauth/asana.js";
+export { buildSpotifyAuthUrl, connectSpotify, exchangeSpotifyCode, refreshSpotifyToken, resolveSpotifyCredential, SPOTIFY_CREDENTIAL_KEY, SPOTIFY_OAUTH_PORT, SPOTIFY_OAUTH_STATE_KEY } from "./oauth/spotify.js";
+export { cancelOAuthFlow, runOAuthFlow } from "./oauth/flow.js";
+export { defaultCredentialKeyFor, GMAIL_CREDENTIAL_KEY, GOOGLE_CALENDAR_CREDENTIAL_KEY, GOOGLE_CREDENTIAL_KEYS, GOOGLE_DOCS_CREDENTIAL_KEY, GOOGLE_DRIVE_CREDENTIAL_KEY, GOOGLE_SHEETS_CREDENTIAL_KEY, LEGACY_GOOGLE_CREDENTIAL_KEY, OAUTH_KEY_SPECS, oauthKeySpec, oauthStateKeyFor } from "./oauth/keys.js";
+export { generatePkceChallenge } from "./oauth/pkce.js";
+export { buildProviderConfig, providerRequiresSecret, providerSupportsDcr, providerSupportsSharedIosSession } from "./oauth/providers.js";
+export { registerOAuthClient, resolveDynamicClientId } from "./oauth/register.js";
+export { isTokenExpired, refreshOAuthTokens } from "./oauth/token-exchange.js";

package/dist-lib/lib/obsidian-key.d.ts

@@ -0,0 +1 @@
+export declare const OBSIDIAN_VAULT_PATH_CREDENTIAL_KEY = "obsidian_vault_path";

package/dist-lib/lib/obsidian-key.js

@@ -0,0 +1 @@
+export const OBSIDIAN_VAULT_PATH_CREDENTIAL_KEY = 'obsidian_vault_path';

package/dist-lib/lib/race-resource.d.ts

@@ -0,0 +1,5 @@
+export interface Closeable {
+    on(event: string, listener: (...args: unknown[]) => void): unknown;
+    off(event: string, listener: (...args: unknown[]) => void): unknown;
+}
+export declare function raceResource<T>(resource: Closeable, operation: Promise<T>, name: string): Promise<T>;

package/dist-lib/lib/race-resource.js

@@ -0,0 +1,25 @@
+export function raceResource(resource, operation, name) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            resource.off('close', onClose);
+            resource.off('error', onError);
+        };
+        const onClose = () => {
+            cleanup();
+            reject(new Error(`${name} closed during open`));
+        };
+        const onError = (...args) => {
+            cleanup();
+            reject(args[0]);
+        };
+        resource.on('close', onClose);
+        resource.on('error', onError);
+        operation.then((value) => {
+            cleanup();
+            resolve(value);
+        }, (err) => {
+            cleanup();
+            reject(err);
+        });
+    });
+}

package/dist-lib/lib/reconnecting-watch.d.ts

@@ -0,0 +1,2 @@
+import type { WatchStream } from './api/index.ts';
+export default function reconnectingWatch<Frame>(open: () => WatchStream<Frame>, onDisconnect: (error: Error) => void): WatchStream<Frame>;

package/dist-lib/lib/reconnecting-watch.js

@@ -0,0 +1,78 @@
+import { Readable } from 'streamx';
+const RETRY_MIN_MS = 250;
+const RETRY_MAX_MS = 5_000;
+export default function reconnectingWatch(open, onDisconnect) {
+    let closeConnection = null;
+    let retry = null;
+    let retryMs = RETRY_MIN_MS;
+    let output;
+    const schedule = (error) => {
+        if (output.destroying)
+            return;
+        onDisconnect(error);
+        retry = setTimeout(() => {
+            retry = null;
+            connect();
+        }, retryMs);
+        retryMs = Math.min(retryMs * 2, RETRY_MAX_MS);
+    };
+    const connect = () => {
+        if (output.destroying)
+            return;
+        let source;
+        try {
+            source = open();
+        }
+        catch (error) {
+            schedule(asError(error));
+            return;
+        }
+        const close = () => {
+            source.off('data', onData);
+            source.off('error', onError);
+            source.off('end', onEnd);
+            source.off('close', onEnd);
+            source.destroy();
+        };
+        const disconnect = (error) => {
+            if (closeConnection !== close)
+                return;
+            closeConnection = null;
+            close();
+            schedule(error);
+        };
+        const onData = (frame) => {
+            retryMs = RETRY_MIN_MS;
+            output.push(frame);
+        };
+        const onError = (error) => disconnect(error);
+        const onEnd = () => disconnect(new Error('Watch stream ended unexpectedly'));
+        closeConnection = close;
+        source.on('data', onData);
+        source.on('error', onError);
+        source.on('end', onEnd);
+        source.on('close', onEnd);
+    };
+    output = new Readable({
+        open(cb) {
+            connect();
+            cb(null);
+        },
+        read(cb) {
+            cb(null);
+        },
+        destroy(cb) {
+            if (retry)
+                clearTimeout(retry);
+            retry = null;
+            const close = closeConnection;
+            closeConnection = null;
+            close?.();
+            cb(null);
+        }
+    });
+    return output;
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}

package/dist-lib/lib/retry-budget.d.ts

@@ -0,0 +1,14 @@
+export interface RetryBudgetOptions {
+    retryMs?: number;
+}
+export declare class RetryBudget {
+    private readonly _retryMs;
+    private readonly _attempts;
+    private readonly _readyAt;
+    constructor({ retryMs }?: RetryBudgetOptions);
+    ready(name: string, now: number): boolean;
+    nextDeadline(names: ReadonlySet<string>, now: number): number | null;
+    reset(name: string): void;
+    retain(names: ReadonlySet<string>): void;
+    fail(name: string, now: number): number;
+}

package/dist-lib/lib/retry-budget.js

@@ -0,0 +1,39 @@
+const DEFAULT_RETRY_MS = 30_000;
+const MAX_RETRY_MS = 15 * 60_000;
+export class RetryBudget {
+    _retryMs;
+    _attempts = new Map();
+    _readyAt = new Map();
+    constructor({ retryMs = DEFAULT_RETRY_MS } = {}) {
+        this._retryMs = retryMs;
+    }
+    ready(name, now) {
+        return (this._readyAt.get(name) ?? 0) <= now;
+    }
+    nextDeadline(names, now) {
+        let next = null;
+        for (const [name, readyAt] of this._readyAt) {
+            if (!names.has(name) || readyAt <= now)
+                continue;
+            if (next === null || readyAt < next)
+                next = readyAt;
+        }
+        return next;
+    }
+    reset(name) {
+        this._attempts.delete(name);
+        this._readyAt.delete(name);
+    }
+    retain(names) {
+        for (const name of this._attempts.keys())
+            if (!names.has(name))
+                this.reset(name);
+    }
+    fail(name, now) {
+        const attempt = (this._attempts.get(name) ?? 0) + 1;
+        this._attempts.set(name, attempt);
+        const at = now + Math.min(this._retryMs * 2 ** (attempt - 1), MAX_RETRY_MS);
+        this._readyAt.set(name, at);
+        return at;
+    }
+}

package/dist-lib/lib/run-notices.d.ts

@@ -0,0 +1,23 @@
+export declare const RUN_ABORT_REASONS: {
+    readonly suspended: "suspended";
+    readonly ownershipLost: "ownership-lost";
+    readonly runSettled: "run-settled";
+    readonly runnerDied: "runner-died";
+    readonly runnerClosed: "runner-closed";
+};
+export type RunAbortReason = (typeof RUN_ABORT_REASONS)[keyof typeof RUN_ABORT_REASONS];
+export declare const RUN_FAILURE_REASONS: {
+    readonly harnessDied: "the model runtime died";
+    readonly runtimeEndedTurn: "the model runtime ended this turn";
+};
+export type AbortOutcome = {
+    readonly kind: 'replay';
+} | {
+    readonly kind: 'handoff';
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+};
+export declare function knownAbortOutcome(reason: unknown): AbortOutcome | null;
+export declare function isLifecycleTeardown(reason: unknown): boolean;
+export declare function runFailureNotice(error: unknown): string;

package/dist-lib/lib/run-notices.js

@@ -0,0 +1,33 @@
+export const RUN_ABORT_REASONS = {
+    suspended: 'suspended',
+    ownershipLost: 'ownership-lost',
+    runSettled: 'run-settled',
+    runnerDied: 'runner-died',
+    runnerClosed: 'runner-closed'
+};
+export const RUN_FAILURE_REASONS = {
+    harnessDied: 'the model runtime died',
+    runtimeEndedTurn: 'the model runtime ended this turn'
+};
+export function knownAbortOutcome(reason) {
+    if (reason === RUN_ABORT_REASONS.suspended || reason === RUN_ABORT_REASONS.runnerClosed) {
+        return { kind: 'replay' };
+    }
+    if (reason === RUN_ABORT_REASONS.ownershipLost || reason === RUN_ABORT_REASONS.runSettled) {
+        return { kind: 'handoff' };
+    }
+    if (reason === RUN_ABORT_REASONS.runnerDied) {
+        return { kind: 'failed', reason: RUN_FAILURE_REASONS.harnessDied };
+    }
+    return null;
+}
+export function isLifecycleTeardown(reason) {
+    return knownAbortOutcome(reason)?.kind === 'replay';
+}
+export function runFailureNotice(error) {
+    if (error instanceof Error && error.message)
+        return error.message;
+    if (typeof error === 'string' && error.trim())
+        return error;
+    return RUN_FAILURE_REASONS.runtimeEndedTurn;
+}

package/dist-lib/lib/run-transcript.d.ts

@@ -0,0 +1,35 @@
+import type { AssistantAppendChunkRequest, AssistantChunkId, AssistantChunkContentRunStatus } from '../spec/hyperschema/types.d.ts';
+import type { Capabilities } from './api/index.ts';
+import type { Logger } from './log.ts';
+export type TranscriptChunk = Pick<AssistantAppendChunkRequest, 'type' | 'toolCall' | 'toolResult' | 'sources' | 'effect' | 'display' | 'rawCall'>;
+export interface RunTranscriptOptions {
+    chatId: string;
+    runId: string;
+    deviceId: Buffer;
+    model: string;
+    log?: Logger | null;
+}
+export declare class RunTranscript {
+    private readonly _engine;
+    private readonly _chatId;
+    private readonly _runId;
+    private readonly _deviceId;
+    private readonly _model;
+    private readonly _log;
+    private readonly _writes;
+    private readonly _ticker;
+    private readonly _announced;
+    private _buffered;
+    constructor(engine: Capabilities, { chatId, runId, deviceId, model, log }: RunTranscriptOptions);
+    text(type: 'content' | 'thinking', text: string): Promise<void>;
+    chunk(chunk: TranscriptChunk): Promise<AssistantChunkId>;
+    status(runStatus: AssistantChunkContentRunStatus): Promise<AssistantChunkId>;
+    progress(id: string, runStatus: AssistantChunkContentRunStatus): Promise<unknown>;
+    flush(): Promise<void>;
+    pending(): Array<{
+        scope: string;
+        waiting: number;
+    }>;
+    close(): void;
+    private _announce;
+}