@north-light/api 0.3.561 → 0.3.563

package/dist/core/git.d.ts

@@ -0,0 +1,28 @@
+export interface GitResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+    /** The child did not exit with a numeric status (for example, spawn failure or timeout). */
+    executionFailed?: true;
+    processError?: string;
+}
+export interface GitSyncOptions {
+    timeoutMs?: number;
+}
+export declare function gitSync(args: string[], cwd?: string, input?: string, options?: GitSyncOptions): GitResult;
+export interface GitAsyncOptions {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function gitAsync(args: string[], cwd?: string, input?: string, options?: GitAsyncOptions): Promise<GitResult>;
+export declare function clone(url: string, dest: string, opts?: {
+    ref?: string;
+    depth?: number;
+}): GitResult;
+export declare function fetch(cwd: string, ref?: string): GitResult;
+export declare function lsRemote(url: string): GitResult;
+export declare function currentSha(cwd: string): string | null;
+export declare function remoteSha(cwd: string, ref: string): string | null;
+export declare function isGitRepo(cwd: string): boolean;
+export declare function deriveNameFromUrl(url: string): string;

package/dist/core/git.js

@@ -0,0 +1,103 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { network } from './errors.js';
+/** Git takes `.git/index.lock` to refresh the index stat cache even during
+ *  otherwise read-only commands — `status` is the common one. Killed between
+ *  creating that lock and renaming it over the index, the lock orphans and
+ *  blocks every later writer in the checkout with no owning process left to
+ *  name. Agent processes are killed mid-command routinely (a closed node, a
+ *  cancelled daemon tick, a timed-out shell), so the residue accumulates.
+ *
+ *  `GIT_OPTIONAL_LOCKS=0` suppresses exactly those optional locks and nothing
+ *  else: a commit, rebase, or `add` still takes the lock it requires, and
+ *  command output is byte-identical. Built per call rather than snapshotted at
+ *  module load, so a later change to the ambient environment still reaches git. */
+function gitEnv(base = process.env) {
+    return { ...base, GIT_OPTIONAL_LOCKS: '0' };
+}
+export function gitSync(args, cwd, input, options = {}) {
+    const res = spawnSync('git', args, { cwd, encoding: 'utf8', input, env: gitEnv(), timeout: options.timeoutMs });
+    const status = typeof res.status === 'number' ? res.status : 1;
+    const completed = typeof res.status === 'number';
+    const stdout = typeof res.stdout === 'string' ? res.stdout : '';
+    const stderr = typeof res.stderr === 'string' ? res.stderr : '';
+    const processError = res.error === undefined ? undefined : String(res.error);
+    const timedOut = res.error?.code === 'ETIMEDOUT';
+    return { status, stdout, stderr, ...(completed ? {} : { executionFailed: true }), ...(processError === undefined ? {} : { processError }), ...(timedOut ? { timedOut: true } : {}) };
+}
+export async function gitAsync(args, cwd, input, options = {}) {
+    return new Promise((resolve) => {
+        const child = spawn('git', args, { cwd, env: gitEnv(options.env) });
+        if (input === undefined)
+            child.stdin.end();
+        else
+            child.stdin.end(input);
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let settled = false;
+        const timer = options.timeoutMs === undefined ? undefined : setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+        }, options.timeoutMs);
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            resolve(result);
+        };
+        child.stdout.on('data', (d) => (stdout += d.toString()));
+        child.stderr.on('data', (d) => (stderr += d.toString()));
+        child.on('close', (status) => {
+            const code = typeof status === 'number' ? status : 1;
+            settle({ status: code, stdout, stderr, ...(timedOut ? { timedOut: true, executionFailed: true } : {}) });
+        });
+        child.on('error', (e) => settle({ status: 1, stdout: '', stderr: String(e), executionFailed: true, processError: String(e) }));
+    });
+}
+export function clone(url, dest, opts = {}) {
+    const args = ['clone'];
+    if (opts.depth)
+        args.push('--depth', String(opts.depth));
+    if (opts.ref)
+        args.push('--branch', opts.ref);
+    args.push(url, dest);
+    const res = gitSync(args);
+    if (res.status !== 0) {
+        throw network(`git clone failed: ${url}\n${res.stderr.trim()}`);
+    }
+    return res;
+}
+export function fetch(cwd, ref) {
+    const args = ['fetch', 'origin'];
+    if (ref)
+        args.push(ref);
+    return gitSync(args, cwd);
+}
+export function lsRemote(url) {
+    return gitSync(['ls-remote', url]);
+}
+export function currentSha(cwd) {
+    const res = gitSync(['rev-parse', 'HEAD'], cwd);
+    if (res.status !== 0)
+        return null;
+    return res.stdout.trim();
+}
+export function remoteSha(cwd, ref) {
+    const res = gitSync(['rev-parse', `origin/${ref}`], cwd);
+    if (res.status !== 0)
+        return null;
+    return res.stdout.trim();
+}
+export function isGitRepo(cwd) {
+    const res = gitSync(['rev-parse', '--is-inside-work-tree'], cwd);
+    return res.status === 0 && res.stdout.trim() === 'true';
+}
+export function deriveNameFromUrl(url) {
+    const trimmed = url.replace(/\.git\/?$/, '').replace(/\/$/, '');
+    const last = trimmed.split('/').pop();
+    if (!last)
+        return url;
+    return last;
+}

package/dist/core/installed-plugins.js

@@ -12,13 +12,13 @@ import { CONFIG_FILE } from '../types.js';
 import { listDirs, pathExists, readJsonIfExists } from './fs-utils.js';
 import { readPluginManifest } from './manifest.js';
 import { awaitBundleSwap, bundleSwapInFlightElsewhere } from './plugin-swap-lock.js';
-import { userStore } from './scoped-state/paths.js';
-import { readRawSettings } from './scoped-state/settings.js';
+import { isCloudRole, requestPersonId } from './canvas/person-state.js';
+import { materializedPluginsDir } from './scoped-state/materialized-plugins.js';
+import { readCachedSettings } from './scoped-state/person-store.js';
 import { pluginsDir } from './scope.js';
 function pluginConfigForRoot(scope, root) {
-    const store = scope === 'user' ? userStore(root) : undefined;
-    const cfg = store
-        ? readRawSettings({ store, key: 'user', kind: 'user', root: store.root })
+    const cfg = scope === 'user'
+        ? readCachedSettings('user').settings
         : readJsonIfExists(join(root, CONFIG_FILE));
     return cfg && cfg.plugins && typeof cfg.plugins === 'object' ? cfg.plugins : {};
 }
@@ -41,8 +41,13 @@ function swapsToWaitOut(scopeRootPath, cfg, present) {
     return names.filter((name) => !present.has(name) && bundleSwapInFlightElsewhere(scopeRootPath, name));
 }
 export function listInstalledPluginsInRoot(scope, scopeRootPath) {
-    const dir = scope === 'user' ? pluginsDir('user') : join(scopeRootPath, 'plugins');
-    if (!pathExists(dir))
+    // A cloud-role process serves many people and holds no plugin directories of its own: it reads the bytes it materialized for the
+    // request's person, and none outside a request.
+    const person = scope === 'user' && isCloudRole() ? requestPersonId() : undefined;
+    if (scope === 'user' && isCloudRole() && person === undefined)
+        return [];
+    const dir = scope !== 'user' ? join(scopeRootPath, 'plugins') : person !== undefined ? materializedPluginsDir(person) : pluginsDir('user');
+    if (dir === undefined || !pathExists(dir))
         return [];
     const cfg = pluginConfigForRoot(scope, scopeRootPath);
     const first = collectInstalledPlugins(scope, dir, cfg);

package/dist/core/managed-providers.d.ts

@@ -0,0 +1,72 @@
+export declare const ANTHROPIC_PROVIDER_ID = "anthropic";
+export declare const OPENAI_CODEX_PROVIDER_ID = "openai-codex";
+/** pi's built-in `openai` provider signed in with a ChatGPT account (dynamic OAuth client). Distinct from Codex: its own pool, credential file and sign-in. */
+export declare const OPENAI_CHATGPT_PROVIDER_ID = "openai";
+/** Longest a recorded 429 keeps an account or model family cooling, whatever the provider's Retry-After or window reset says: after this the next real call probes the provider, and a success clears the row. */
+export declare const MAX_RATE_LIMIT_COOLDOWN_MS: number;
+export declare const INVALID_REFRESH_TOKEN_BACKOFF_MS: number;
+export type ManagedProviderId = typeof ANTHROPIC_PROVIDER_ID | typeof OPENAI_CODEX_PROVIDER_ID | typeof OPENAI_CHATGPT_PROVIDER_ID;
+export declare const MANAGED_PROVIDER_IDS: readonly ManagedProviderId[];
+export type ModelStrength = 'ultra' | 'strong' | 'medium' | 'light';
+export type RotationConfig = {
+    defaultFallbackStrength?: ModelStrength;
+    revertWhenAvailable?: boolean;
+};
+/** `rateLimitedUntil` cools the whole account; `modelCooldowns` cools one model family on it (family → epoch ms, stored rows including expired ones). Read both through `coolingUntilFor`. */
+export type SubscriptionCredential = {
+    label: string;
+    refresh: string;
+    access: string;
+    expires: number;
+    rateLimitedUntil: number;
+    lastAttemptAt: number;
+    lastRateLimitedAt: number;
+    authFailure?: 'invalid_grant';
+    accountId?: string;
+    clientId?: string;
+    modelCooldowns?: Record<string, number>;
+};
+export type ProviderCandidate = {
+    providerId: string;
+    modelId: string;
+    thinkingLevel?: string;
+    registered: boolean;
+    authenticated: boolean;
+    coolingUntil?: number;
+    automaticFallback?: boolean;
+    routeId?: string;
+    credentialSource?: string;
+    family?: string;
+    strength?: ModelStrength;
+    rank?: number;
+};
+export type ProviderCandidateRejection = 'unregistered' | 'non-managed-fallback' | 'unauthenticated' | 'cooling';
+/** When this account can next serve `modelId`: the later of its account-wide cooldown and the cooldown on that model's family. Without a model only the account-wide cooldown applies. 0 or a past time means ready. */
+export declare function coolingUntilFor(entry: Pick<SubscriptionCredential, 'rateLimitedUntil' | 'modelCooldowns'>, modelId?: string): number;
+/** Every cooldown on an account still in force at `now`: `scope` is `account` or the model family. */
+export declare function activeCooldowns(entry: Pick<SubscriptionCredential, 'rateLimitedUntil' | 'modelCooldowns'>, now?: number): Array<{
+    scope: string;
+    until: number;
+}>;
+/** Human text for an account's active cooldowns (`cooldown 12m`, `opus cooldown 3d 4h`), or undefined when it is ready. */
+export declare function formatCooldowns(entry: Pick<SubscriptionCredential, 'rateLimitedUntil' | 'modelCooldowns'>, now?: number): string | undefined;
+/** Whether a successful call on `modelId` has stored cooldown or auth health to clear; callers skip the write otherwise (every provider write bumps provider_revision). */
+export declare function subscriptionNeedsSuccessWrite(entry: Pick<SubscriptionCredential, 'rateLimitedUntil' | 'authFailure' | 'modelCooldowns'>, modelId?: string): boolean;
+export declare function isManagedProvider(providerId: string | undefined): providerId is ManagedProviderId;
+export declare function getProviderLabel(providerId: ManagedProviderId): string;
+export declare function resolveProviderCandidates(candidates: readonly ProviderCandidate[], now?: number, options?: {
+    pinnedToFirst?: boolean;
+}): {
+    candidates: ProviderCandidate[];
+    rejected: Array<{
+        candidate: ProviderCandidate;
+        reason: ProviderCandidateRejection;
+    }>;
+};
+export declare class DuplicateSubscriptionError extends Error {
+    constructor(message: string);
+}
+export declare function isInvalidRefreshTokenError(error: unknown): boolean;
+export declare function parseRetryAfterHeader(value: string | undefined, now?: number): number | undefined;
+export declare function retryAfterMsFromHeaders(headers: Headers | Record<string, string> | undefined): number | undefined;
+export declare function retryAfterMsFromError(error: unknown): number | undefined;

package/dist/core/managed-providers.js

@@ -0,0 +1,61 @@
+// Pure managed-provider vocabulary: ids, credential/candidate types, cooldown arithmetic, retry-after parsing.
+// No database or secrets imports, so CLI entrypoints can use it; the pool rows live in subscription-state.ts (daemon only).
+import { modelCooldownFamily } from './rate-limit-scope.js';
+export const ANTHROPIC_PROVIDER_ID = 'anthropic';
+export const OPENAI_CODEX_PROVIDER_ID = 'openai-codex';
+/** pi's built-in `openai` provider signed in with a ChatGPT account (dynamic OAuth client). Distinct from Codex: its own pool, credential file and sign-in. */
+export const OPENAI_CHATGPT_PROVIDER_ID = 'openai';
+/** Longest a recorded 429 keeps an account or model family cooling, whatever the provider's Retry-After or window reset says: after this the next real call probes the provider, and a success clears the row. */
+export const MAX_RATE_LIMIT_COOLDOWN_MS = 10 * 60 * 1000;
+export const INVALID_REFRESH_TOKEN_BACKOFF_MS = 30 * 24 * 60 * 60 * 1000;
+export const MANAGED_PROVIDER_IDS = [ANTHROPIC_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID, OPENAI_CHATGPT_PROVIDER_ID];
+const PROVIDERS = { anthropic: { label: 'Claude' }, 'openai-codex': { label: 'OpenAI Codex' }, openai: { label: 'ChatGPT' } };
+/** When this account can next serve `modelId`: the later of its account-wide cooldown and the cooldown on that model's family. Without a model only the account-wide cooldown applies. 0 or a past time means ready. */
+export function coolingUntilFor(entry, modelId) { const family = modelCooldownFamily(modelId); return Math.max(entry.rateLimitedUntil || 0, family === undefined ? 0 : entry.modelCooldowns?.[family] ?? 0); }
+/** Every cooldown on an account still in force at `now`: `scope` is `account` or the model family. */
+export function activeCooldowns(entry, now = Date.now()) { return [...((entry.rateLimitedUntil || 0) > now ? [{ scope: 'account', until: entry.rateLimitedUntil }] : []), ...Object.entries(entry.modelCooldowns ?? {}).filter(([, until]) => until > now).map(([scope, until]) => ({ scope, until }))]; }
+/** Human text for an account's active cooldowns (`cooldown 12m`, `opus cooldown 3d 4h`), or undefined when it is ready. */
+export function formatCooldowns(entry, now = Date.now()) { const parts = activeCooldowns(entry, now).map(({ scope, until }) => `${scope === 'account' ? '' : `${scope} `}cooldown ${formatWait(until - now)}`); return parts.length ? parts.join(', ') : undefined; }
+function formatWait(ms) { const minutes = Math.max(1, Math.ceil(ms / 60_000)); if (minutes < 60)
+    return `${minutes}m`; const hours = Math.floor(minutes / 60); if (hours < 24)
+    return `${hours}h${minutes % 60 ? ` ${minutes % 60}m` : ''}`; return `${Math.floor(hours / 24)}d${hours % 24 ? ` ${hours % 24}h` : ''}`; }
+function hasModelCooldownRow(entry, modelId) { const family = modelCooldownFamily(modelId); return family !== undefined && entry.modelCooldowns?.[family] !== undefined; }
+/** Whether a successful call on `modelId` has stored cooldown or auth health to clear; callers skip the write otherwise (every provider write bumps provider_revision). */
+export function subscriptionNeedsSuccessWrite(entry, modelId) { return Boolean(entry.rateLimitedUntil || entry.authFailure) || hasModelCooldownRow(entry, modelId); }
+export function isManagedProvider(providerId) { return providerId === ANTHROPIC_PROVIDER_ID || providerId === OPENAI_CODEX_PROVIDER_ID || providerId === OPENAI_CHATGPT_PROVIDER_ID; }
+export function getProviderLabel(providerId) { return PROVIDERS[providerId].label; }
+export function resolveProviderCandidates(candidates, now = Date.now(), options = {}) { const viable = []; const rejected = []; for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i];
+    const reason = !candidate.registered ? 'unregistered' : candidate.automaticFallback === false ? 'non-managed-fallback' : !candidate.authenticated ? 'unauthenticated' : (candidate.coolingUntil ?? 0) > now ? 'cooling' : undefined;
+    if (!reason)
+        viable.push(candidate);
+    else {
+        rejected.push({ candidate, reason });
+        if (options.pinnedToFirst && i === 0 && reason !== 'cooling')
+            break;
+    }
+} return { candidates: viable, rejected }; }
+export class DuplicateSubscriptionError extends Error {
+    constructor(message) { super(message); this.name = 'DuplicateSubscriptionError'; }
+}
+export function isInvalidRefreshTokenError(error) { const value = error; const message = [value?.errorMessage, value?.message, error instanceof Error ? error.message : ''].filter((part) => typeof part === 'string').join(' '); const status = typeof value?.status === 'number' ? value.status : Number(message.match(/\bstatus[=:]\s*(\d+)/i)?.[1]); return status === 400 && /invalid_grant|refresh token .*invalid|refresh token .*not found/i.test(message); }
+export function parseRetryAfterHeader(value, now = Date.now()) { if (!value?.trim())
+    return undefined; const seconds = Number(value.trim()); if (Number.isFinite(seconds))
+    return Math.max(0, Math.round(seconds * 1000)); const parsed = Date.parse(value); return Number.isFinite(parsed) ? Math.max(0, parsed - now) : undefined; }
+export function retryAfterMsFromHeaders(headers) {
+    if (!headers)
+        return undefined;
+    const get = (name) => headers instanceof Headers ? headers.get(name) ?? undefined : Object.entries(headers).find(([key]) => key.toLowerCase() === name)?.[1];
+    const millis = get('retry-after-ms');
+    if (millis !== undefined && millis.trim() !== '' && Number.isFinite(Number(millis)))
+        return Math.max(0, Number(millis));
+    return parseRetryAfterHeader(get('retry-after'));
+}
+export function retryAfterMsFromError(error) {
+    if (!error || typeof error !== 'object' || !('headers' in error))
+        return undefined;
+    const headers = error.headers;
+    if (!(headers instanceof Headers) && (!headers || typeof headers !== 'object' || Array.isArray(headers)))
+        return undefined;
+    return retryAfterMsFromHeaders(headers);
+}

package/dist/core/plugin-env.js

@@ -1,5 +1,4 @@
-import { validateEnvVarName } from './env-name.js';
-import { isReservedEnvName } from './profiles/env-store.js';
+import { isReservedEnvName, validateEnvVarName } from './env-name.js';
 export function invalidPluginEnvReasons(raw) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
         return ['env must be an object mapping variable names to declarations'];

package/dist/core/profiles/manifest.d.ts

@@ -55,11 +55,7 @@ export declare function resolveProfileOperand(operand: string): ProfileEntry;
 /** `resolveProfileOperand` over any candidate list — the CLI passes the
  *  profiles the daemon lists for its caller. */
 export declare function matchProfileOperand<T>(all: readonly T[], operand: string, key: CandidateOf<T>): T;
-/** Hold the per-profile manifest lock for the duration of `fn`. ALL manifest
- *  mutations (create/rename/add-project/remove-project/delete/last-used)
- *  below run inside this. */
-export declare function withProfileManifestLock<T>(profileId: string, fn: () => T): T;
-export declare function ensureRootProfile(): ProfileEntry;
+export declare function ensureRootProfile(): Promise<ProfileEntry>;
 /** The env name a metadata entry surfaces as (spawn-env source F). Also the
  *  uniqueness domain for keys: the fold is lossy (`a-b`, `a_b`, `A_B` →
  *  `CRTR_PROFILE_META_A_B`), so two stored keys may not share a fold. */
@@ -77,9 +73,9 @@ export declare function createProfile(name: string, projects?: ProfileProject[],
     defaultKind?: string;
     metadata?: Record<string, string>;
     grantee?: string;
-}): ProfileEntry;
-export declare function ensureAppProfile(grantee: string): ProfileEntry;
-export declare function updateProfileLastUsed(profileId: string): ProfileEntry;
+}): Promise<ProfileEntry>;
+export declare function ensureAppProfile(grantee: string): Promise<ProfileEntry>;
+export declare function updateProfileLastUsed(profileId: string): Promise<ProfileEntry>;
 /** Paused check for an ALREADY-RESOLVED durable id (a canvas row's `profile_id`,
  * `CRTR_PROFILE_ID`) — exact-id only, no name matching, so it costs one small
  * read on the hot delivery paths that call it every poll. Fails OPEN: an id
@@ -92,14 +88,14 @@ export declare function pausedCanvasProfiles(): Set<string>;
  * every gate that already holds a loaded manifest. */
 export declare function assertProfileEntryActive(entry: ProfileEntry): void;
 export declare function assertProfileActive(profileId: string | null | undefined): ProfileEntry | null;
-export declare function pauseProfile(profileId: string): ProfileEntry;
-export declare function resumeProfile(profileId: string): ProfileEntry & {
+export declare function pauseProfile(profileId: string): Promise<ProfileEntry>;
+export declare function resumeProfile(profileId: string): Promise<ProfileEntry & {
     pausedAt: string | null;
-};
-export declare function setProfileDefaultKind(profileId: string, defaultKind: string): ProfileEntry;
+}>;
+export declare function setProfileDefaultKind(profileId: string, defaultKind: string): Promise<ProfileEntry>;
 /** Merge `set` entries over the stored map and drop `unset` keys; the
  *  `metadata` field is omitted entirely when the result is empty. */
-export declare function updateProfileMetadata(profileId: string, set: Record<string, string>, unset?: string[]): ProfileEntry;
+export declare function updateProfileMetadata(profileId: string, set: Record<string, string>, unset?: string[]): Promise<ProfileEntry>;
 /** A profile's stored metadata for broker-env injection — sanitized entry by
  *  entry (a manifest is hand-editable, so a bad key/value is dropped rather
  *  than trusted) and never throwing: a stale/invalid/absent profile id is a
@@ -109,12 +105,12 @@ export declare function readProfileMetadata(profileId: string | null): Record<st
 /** Change the manifest `name` only. Callers that own the canvas (the daemon's
  *  `PATCH /v1/profiles/:name`) must also rename the profile's canvas handle —
  *  use `renameProfileAndHandle` there; the CLI and panels go through that route. */
-export declare function renameProfile(profileId: string, name: string): ProfileEntry;
+export declare function renameProfile(profileId: string, name: string): Promise<ProfileEntry>;
 /** A new path appends; a path already listed keeps its position. */
-export declare function addProfileProject(profileId: string, dir: string): ProfileEntry;
+export declare function addProfileProject(profileId: string, dir: string): Promise<ProfileEntry>;
 /** Set one owner's automatic delivery limit. `content` is the uncapped level,
  *  so it removes the owner's entry instead of storing it. */
-export declare function setProfileDeliveryLimit(profileId: string, owner: string, level: ProfileProjectMemory): ProfileEntry;
-export declare function removeProfileProject(profileId: string, dir: string): ProfileEntry;
-export declare function deleteProfile(profileId: string): void;
+export declare function setProfileDeliveryLimit(profileId: string, owner: string, level: ProfileProjectMemory): Promise<ProfileEntry>;
+export declare function removeProfileProject(profileId: string, dir: string): Promise<ProfileEntry>;
+export declare function deleteProfile(profileId: string): Promise<void>;
 export {};