crewly 1.20.209 → 1.20.210

package/dist/backend/backend/src/services/apps/app-wake.service.js

@@ -0,0 +1,325 @@
+/**
+ * AppWakeService — polls the change feed of every app this instance
+ * published and wakes the agent that published it when the owner changes
+ * something (specs/2026-10-04-crewly-apps-p2.md §5).
+ *
+ * - Every POLL_INTERVAL_MS, the apps that are due are polled with
+ *   `GET changes?since=<cursor>&wait=0`, POLL_CONCURRENCY at a time, each
+ *   request capped at POLL_REQUEST_TIMEOUT_MS. A failing app backs off on
+ *   its own (×2 up to POLL_MAX_BACKOFF_MS); the others keep their cadence.
+ * - Only owner changes wake (data written in the app, `notify` / `ask`);
+ *   every agent write — the agent's own included — is skipped.
+ * - The first change for (app, recipient) opens a BATCH_WINDOW_MS window; a
+ *   successful wake starts a COOLDOWN_MS quiet period (persisted, so it
+ *   survives a restart) during which changes keep collecting.
+ * - A failed delivery keeps the batch (and the cursor before it) and is
+ *   retried with backoff; after WAKE_FAILS_BEFORE_ORC_NOTICE failures the
+ *   orchestrator is told once.
+ * - An `ask` reaches a named agent only when it is in the publisher's team
+ *   and already running; it never starts a stopped agent.
+ *
+ * @module services/apps/app-wake.service
+ */
+import { CREWLY_APPS_CONSTANTS } from '../../constants.js';
+import { LoggerService } from '../core/logger.service.js';
+import { AppsCloudError } from './apps-cloud.client.js';
+import { buildAppWakeMessage, safeAppName } from './app-wake-message.js';
+const C = CREWLY_APPS_CONSTANTS;
+/** Recipient key for the orchestrator (never a valid session name). */
+export const ORC_RECIPIENT = '\u0000orchestrator';
+/**
+ * Change poller and agent waker for Crewly Apps.
+ */
+export class AppWakeService {
+    deps;
+    now;
+    logger;
+    timer = null;
+    running = false;
+    ticking = null;
+    batches = new Map();
+    lastWakeAt = new Map();
+    /** Highest seq read per app (the registry holds what is safe to persist) */
+    fetched = new Map();
+    /** Seqs above the safe cursor already delivered, per app */
+    delivered = new Map();
+    backoff = new Map();
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? (() => Date.now());
+        this.logger = deps.logger ?? LoggerService.getInstance().createComponentLogger('AppWake');
+    }
+    /** Start polling (first tick after one interval). */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.schedule();
+    }
+    /** Stop polling and drop timers. Unsent batches stay behind the persisted cursor and are re-read next start. */
+    stop() {
+        this.running = false;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        for (const b of this.batches.values())
+            if (b.timer)
+                clearTimeout(b.timer);
+        this.batches.clear();
+    }
+    /**
+     * Per-app backoff state (tests).
+     *
+     * @param appId - App id
+     * @returns Failures in a row and when the app is next due, or null when healthy
+     */
+    appBackoff(appId) {
+        const b = this.backoff.get(appId);
+        return b ? { ...b } : null;
+    }
+    schedule() {
+        if (!this.running)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.tick().finally(() => this.schedule());
+        }, C.POLL_INTERVAL_MS);
+        this.timer.unref?.();
+    }
+    /**
+     * One pass over the apps that are due. Exposed for tests and for an immediate poll.
+     */
+    async tick() {
+        if (this.ticking)
+            return this.ticking;
+        this.ticking = this.runTick().finally(() => {
+            this.ticking = null;
+        });
+        return this.ticking;
+    }
+    async runTick() {
+        if (!this.deps.client.isAvailable())
+            return;
+        const now = this.now();
+        const due = (await this.deps.registry.list()).filter((e) => !e.deleted && (this.backoff.get(e.appId)?.nextAt ?? 0) <= now);
+        let next = 0;
+        const worker = async () => {
+            while (next < due.length) {
+                const app = due[next++];
+                await this.pollOne(app);
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(C.POLL_CONCURRENCY, due.length) }, worker));
+    }
+    async pollOne(app) {
+        try {
+            await this.pollApp(app);
+            this.backoff.delete(app.appId);
+        }
+        catch (err) {
+            if (err instanceof AppsCloudError && err.status === 404) {
+                this.logger.info('App no longer exists in Crewly Cloud; stopped polling it', { appId: app.appId });
+                await this.deps.registry.markDeleted(app.appId);
+                this.backoff.delete(app.appId);
+                return;
+            }
+            const failures = (this.backoff.get(app.appId)?.failures ?? 0) + 1;
+            const wait = Math.min(C.POLL_INTERVAL_MS * 2 ** failures, C.POLL_MAX_BACKOFF_MS);
+            this.backoff.set(app.appId, { failures, nextAt: this.now() + wait });
+            this.logger.warn('Polling app changes failed', { appId: app.appId, failures, retryInMs: wait, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    deliveredSet(app) {
+        let set = this.delivered.get(app.appId);
+        if (!set) {
+            set = new Set(app.delivered ?? []);
+            this.delivered.set(app.appId, set);
+        }
+        return set;
+    }
+    async pollApp(app) {
+        const opts = { timeoutMs: C.POLL_REQUEST_TIMEOUT_MS };
+        if (app.cursor === null || app.cursor === undefined) {
+            // Never polled: start from now, never replay history.
+            const head = await this.deps.client.request('GET', `/apps/${app.appId}/changes`, opts);
+            this.fetched.set(app.appId, head.seq);
+            await this.deps.registry.setProgress(app.appId, head.seq, []);
+            return;
+        }
+        const done = this.deliveredSet(app);
+        let since = Math.max(app.cursor, this.fetched.get(app.appId) ?? app.cursor);
+        for (let page = 0; page < C.POLL_MAX_PAGES; page++) {
+            const res = await this.deps.client.request('GET', `/apps/${app.appId}/changes`, { ...opts, query: { since, wait: 0 } });
+            const changes = Array.isArray(res.changes) ? res.changes : [];
+            for (const change of changes) {
+                if (typeof change.seq === 'number' && change.seq > since && !done.has(change.seq))
+                    await this.handle(app, change);
+            }
+            since = Math.max(since, typeof res.seq === 'number' ? res.seq : since);
+            this.fetched.set(app.appId, since);
+            if (changes.length < C.CHANGES_PAGE)
+                break;
+        }
+        await this.persistProgress(app.appId);
+    }
+    /**
+     * Persist the safe cursor — before the first change of any unsent batch
+     * for the app — plus the seqs above it that were already delivered, so a
+     * restart neither loses a pending batch nor repeats a delivered one.
+     */
+    async persistProgress(appId) {
+        const fetched = this.fetched.get(appId);
+        if (fetched === undefined)
+            return;
+        let safe = fetched;
+        for (const b of this.batches.values()) {
+            if (b.appId === appId)
+                safe = Math.min(safe, b.firstSeq - 1);
+        }
+        const set = this.delivered.get(appId) ?? new Set();
+        for (const seq of set)
+            if (seq <= safe)
+                set.delete(seq);
+        while (set.size > C.MAX_DELIVERED_SEQS)
+            set.delete(Math.min(...set));
+        this.delivered.set(appId, set);
+        await this.deps.registry.setProgress(appId, safe, [...set]);
+    }
+    async recipientFor(app, change) {
+        const publisher = app.agentSession ?? null;
+        const named = change.kind === 'event' && change.event?.type === 'ask' ? change.event.agent : undefined;
+        if (publisher && typeof named === 'string' && this.deps.resolveAgent) {
+            const target = await this.deps.resolveAgent(named, publisher).catch(() => null);
+            // Only a running teammate; an ask never starts a stopped agent.
+            if (target && target !== publisher && this.deps.isRunning?.(target))
+                return { session: target, activate: false };
+        }
+        return { session: publisher, activate: true };
+    }
+    async handle(app, change) {
+        // Only the owner's changes wake; any agent write (its own included) does not.
+        if (change.actor?.kind !== 'owner')
+            return;
+        if (change.kind === 'event') {
+            if (change.event?.type !== 'notify' && change.event?.type !== 'ask')
+                return;
+        }
+        else if (change.kind !== 'data') {
+            return;
+        }
+        const { session, activate } = await this.recipientFor(app, change);
+        const recipient = session ?? ORC_RECIPIENT;
+        const key = `${app.appId}\u0000${recipient}`;
+        let batch = this.batches.get(key);
+        if (!batch) {
+            const last = this.lastWakeAt.get(key) ?? app.wakes?.[recipient] ?? -Infinity;
+            const delay = Math.max(C.BATCH_WINDOW_MS, last + C.COOLDOWN_MS - this.now());
+            batch = {
+                appId: app.appId,
+                session,
+                activate,
+                dataChanges: [],
+                events: [],
+                dataTotal: 0,
+                eventsTotal: 0,
+                seqs: [],
+                firstSeq: change.seq,
+                timer: null,
+                failures: 0,
+                orcNotified: false,
+            };
+            this.batches.set(key, batch);
+            this.arm(key, batch, delay);
+        }
+        batch.seqs.push(change.seq);
+        if (batch.seqs.length > C.MAX_DELIVERED_SEQS)
+            batch.seqs.shift();
+        if (change.kind === 'event') {
+            batch.eventsTotal++;
+            batch.events.push(change);
+            if (batch.events.length > C.MAX_EVENTS_PER_WAKE)
+                batch.events.shift();
+        }
+        else {
+            batch.dataTotal++;
+            batch.dataChanges.push(change);
+            if (batch.dataChanges.length > C.MAX_BATCH_DATA_CHANGES)
+                batch.dataChanges.shift();
+        }
+    }
+    arm(key, batch, delay) {
+        if (batch.timer)
+            clearTimeout(batch.timer);
+        batch.timer = setTimeout(() => void this.flush(key), delay);
+        batch.timer.unref?.();
+    }
+    /**
+     * Send one batch now (timer callback; tests). On failure the batch stays
+     * pending and is retried with backoff.
+     *
+     * @param key - Batch key
+     * @returns Whether a message was delivered
+     */
+    async flush(key) {
+        const batch = this.batches.get(key);
+        if (!batch)
+            return false;
+        if (batch.timer)
+            clearTimeout(batch.timer);
+        batch.timer = null;
+        const app = await this.deps.registry.get(batch.appId);
+        const recipient = batch.session ?? ORC_RECIPIENT;
+        const text = buildAppWakeMessage({
+            appId: batch.appId,
+            appName: app?.name ?? batch.appId,
+            isPublisher: (app?.agentSession ?? null) === batch.session,
+            dataChanges: batch.dataChanges,
+            events: batch.events,
+            dataTotal: batch.dataTotal,
+            eventsTotal: batch.eventsTotal,
+            skillsPath: this.deps.skillsPath,
+        });
+        let ok = false;
+        try {
+            ok = await this.deps.deliver(batch.session, text, { activate: batch.activate });
+        }
+        catch (err) {
+            this.logger.warn('App change wake failed', { appId: batch.appId, session: batch.session, error: err instanceof Error ? err.message : String(err) });
+        }
+        if (!ok) {
+            batch.failures++;
+            const retry = Math.min(C.WAKE_RETRY_BASE_MS * 2 ** (batch.failures - 1), C.WAKE_RETRY_MAX_MS);
+            this.logger.warn('App change wake was not delivered; will retry', { appId: batch.appId, session: batch.session ?? 'orchestrator', failures: batch.failures, retryInMs: retry });
+            if (batch.failures >= C.WAKE_FAILS_BEFORE_ORC_NOTICE && !batch.orcNotified && batch.session !== null) {
+                batch.orcNotified = true;
+                const notice = `[APP CHANGES] The owner's changes in app "${safeAppName(app?.name ?? batch.appId)}" (${batch.appId}) could not be delivered to ` +
+                    `${batch.session} after ${batch.failures} tries. Crewly keeps retrying. Check whether that agent is stuck or signed out.`;
+                await this.deps.deliver(null, notice, { activate: false }).catch(() => false);
+            }
+            if (this.batches.get(key) === batch)
+                this.arm(key, batch, retry);
+            return false;
+        }
+        this.batches.delete(key);
+        const at = this.now();
+        this.lastWakeAt.set(key, at);
+        await this.deps.registry.setLastWake(batch.appId, recipient, at).catch(() => undefined);
+        const set = this.delivered.get(batch.appId) ?? new Set();
+        for (const seq of batch.seqs)
+            set.add(seq);
+        this.delivered.set(batch.appId, set);
+        this.logger.info('Woke agent for app changes', {
+            appId: batch.appId,
+            session: batch.session ?? 'orchestrator',
+            dataChanges: batch.dataTotal,
+            events: batch.eventsTotal,
+        });
+        await this.persistProgress(batch.appId).catch(() => undefined);
+        return true;
+    }
+    /** @returns Keys of batches waiting to be sent (tests) */
+    pendingKeys() {
+        return [...this.batches.keys()];
+    }
+}
+//# sourceMappingURL=app-wake.service.js.map

package/dist/backend/backend/src/services/apps/app-wake.service.js.map

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

package/dist/backend/backend/src/services/apps/apps-cloud.client.d.ts

@@ -0,0 +1,74 @@
+/**
+ * AppsCloudClient — this instance's calls to the Crewly Apps agent API
+ * (`<cloudUrl>/api/apps/v1`, crewly-services apps/SPEC.md §3.1).
+ *
+ * Authenticates with the Cloud access token the {@link CloudClientService}
+ * holds and refreshes, bound to this instance (`X-Crewly-Instance`) and
+ * attributed to the calling agent (`X-Crewly-Agent`). Agents never see the
+ * token: they reach this through `/api/apps` (specs/2026-10-04-crewly-apps-p2.md).
+ *
+ * @module services/apps/apps-cloud.client
+ */
+/** The slice of the Cloud client used here (injectable for tests). */
+export interface AppsCloudSession {
+    isConnected(): boolean;
+    getToken(): string | null;
+    getCloudUrl(): string | null;
+    tryRefreshToken(): Promise<boolean>;
+}
+/** Constructor dependencies. */
+export interface AppsCloudClientDeps {
+    cloud?: AppsCloudSession;
+    /** This instance's Cloud device id (the Slack instance registry's id) */
+    instanceId: () => Promise<string | null>;
+    fetchImpl?: typeof fetch;
+}
+/** A failed Apps call: HTTP status and a stable code for the controller and skills. */
+export declare class AppsCloudError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+/** Options of one request. */
+export interface AppsRequestOptions {
+    /** JSON body */
+    body?: unknown;
+    /** Query parameters (undefined values are dropped) */
+    query?: Record<string, string | number | undefined>;
+    /** Agent session to attribute the call to; omitted for the owner */
+    agent?: string;
+    /** Request timeout (default REQUEST_TIMEOUT_MS) */
+    timeoutMs?: number;
+}
+/**
+ * Typed wrapper over the Apps agent API.
+ */
+export declare class AppsCloudClient {
+    private readonly deps;
+    private readonly cloud;
+    private readonly fetchImpl;
+    constructor(deps: AppsCloudClientDeps);
+    /**
+     * Whether a Cloud login is present (a call can be attempted).
+     *
+     * @returns True when connected with a token and URL
+     */
+    isAvailable(): boolean;
+    /**
+     * Call the Apps API and return its `data`.
+     *
+     * A 401 refreshes the Cloud token once and retries. Cloud's
+     * `{ success:false, error, code }` becomes an {@link AppsCloudError} with
+     * Cloud's status and code. The token is never part of an error.
+     *
+     * @param method - HTTP method
+     * @param path - Path under `/api/apps/v1` (starts with `/`)
+     * @param opts - Body, query, agent attribution
+     * @returns The response `data`
+     * @throws AppsCloudError not_logged_in / instance_unknown / network / Cloud's code
+     */
+    request<T>(method: string, path: string, opts?: AppsRequestOptions): Promise<T>;
+    private static readJson;
+    private send;
+}
+//# sourceMappingURL=apps-cloud.client.d.ts.map

package/dist/backend/backend/src/services/apps/apps-cloud.client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps-cloud.client.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/apps/apps-cloud.client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,WAAW,IAAI,OAAO,CAAC;IACvB,QAAQ,IAAI,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,IAAI,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACrC;AAED,gCAAgC;AAChC,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,yEAAyE;IACzE,UAAU,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,uFAAuF;AACvF,qBAAa,cAAe,SAAQ,KAAK;aAErB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;gBADZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAED,8BAA8B;AAC9B,MAAM,WAAW,kBAAkB;IACjC,gBAAgB;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IACpD,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,eAAe;IAId,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAEZ,IAAI,EAAE,mBAAmB;IAKtD;;;;OAIG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;;;;;;;;OAYG;IACG,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,CAAC,CAAC;mBAwBpE,QAAQ;YASf,IAAI;CAwBnB"}

package/dist/backend/backend/src/services/apps/apps-cloud.client.js

@@ -0,0 +1,120 @@
+/**
+ * AppsCloudClient — this instance's calls to the Crewly Apps agent API
+ * (`<cloudUrl>/api/apps/v1`, crewly-services apps/SPEC.md §3.1).
+ *
+ * Authenticates with the Cloud access token the {@link CloudClientService}
+ * holds and refreshes, bound to this instance (`X-Crewly-Instance`) and
+ * attributed to the calling agent (`X-Crewly-Agent`). Agents never see the
+ * token: they reach this through `/api/apps` (specs/2026-10-04-crewly-apps-p2.md).
+ *
+ * @module services/apps/apps-cloud.client
+ */
+import { CREWLY_APPS_CONSTANTS } from '../../constants.js';
+import { CloudClientService } from '../cloud/cloud-client.service.js';
+const C = CREWLY_APPS_CONSTANTS;
+/** A failed Apps call: HTTP status and a stable code for the controller and skills. */
+export class AppsCloudError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'AppsCloudError';
+    }
+}
+/**
+ * Typed wrapper over the Apps agent API.
+ */
+export class AppsCloudClient {
+    deps;
+    cloud;
+    fetchImpl;
+    constructor(deps) {
+        this.deps = deps;
+        this.cloud = deps.cloud ?? CloudClientService.getInstance();
+        this.fetchImpl = deps.fetchImpl ?? fetch;
+    }
+    /**
+     * Whether a Cloud login is present (a call can be attempted).
+     *
+     * @returns True when connected with a token and URL
+     */
+    isAvailable() {
+        return this.cloud.isConnected() && !!this.cloud.getToken() && !!this.cloud.getCloudUrl();
+    }
+    /**
+     * Call the Apps API and return its `data`.
+     *
+     * A 401 refreshes the Cloud token once and retries. Cloud's
+     * `{ success:false, error, code }` becomes an {@link AppsCloudError} with
+     * Cloud's status and code. The token is never part of an error.
+     *
+     * @param method - HTTP method
+     * @param path - Path under `/api/apps/v1` (starts with `/`)
+     * @param opts - Body, query, agent attribution
+     * @returns The response `data`
+     * @throws AppsCloudError not_logged_in / instance_unknown / network / Cloud's code
+     */
+    async request(method, path, opts = {}) {
+        if (!this.isAvailable()) {
+            throw new AppsCloudError(409, C.ERROR_CODES.NOT_LOGGED_IN, 'This machine is not signed in to Crewly Cloud. Run `crewly cloud login`.');
+        }
+        const instanceId = await this.deps.instanceId();
+        if (!instanceId) {
+            throw new AppsCloudError(409, C.ERROR_CODES.NO_INSTANCE, 'This machine has no Crewly Cloud instance id yet. Sign in to Crewly Cloud and try again in a minute.');
+        }
+        let res = await this.send(method, path, opts, instanceId);
+        if (res.status === 401 && (await this.cloud.tryRefreshToken().catch(() => false))) {
+            res = await this.send(method, path, opts, instanceId);
+        }
+        const json = await AppsCloudClient.readJson(res);
+        if (res.ok && json && json.success !== false)
+            return json.data;
+        const code = typeof json?.code === 'string' ? json.code : res.status === 401 ? C.ERROR_CODES.NOT_LOGGED_IN : `http_${res.status}`;
+        const message = typeof json?.error === 'string'
+            ? json.error
+            : res.status === 401
+                ? 'Crewly Cloud rejected the session. Run `crewly cloud login` again.'
+                : `Crewly Apps request failed (${res.status}).`;
+        throw new AppsCloudError(res.status === 401 ? 409 : res.status, code, message);
+    }
+    static async readJson(res) {
+        try {
+            const parsed = await res.json();
+            return parsed && typeof parsed === 'object' ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async send(method, path, opts, instanceId) {
+        const base = `${(this.cloud.getCloudUrl() ?? '').replace(/\/+$/, '')}${C.CLOUD_PATH}`;
+        const url = new URL(`${base}${path}`);
+        for (const [k, v] of Object.entries(opts.query ?? {})) {
+            if (v !== undefined && v !== '')
+                url.searchParams.set(k, String(v));
+        }
+        const headers = {
+            Authorization: `Bearer ${this.cloud.getToken() ?? ''}`,
+            'X-Crewly-Instance': instanceId,
+        };
+        if (opts.agent)
+            headers['X-Crewly-Agent'] = opts.agent;
+        if (opts.body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        try {
+            return await this.fetchImpl(url.toString(), {
+                method,
+                headers,
+                ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+                signal: AbortSignal.timeout(opts.timeoutMs ?? C.REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch (err) {
+            const why = err instanceof Error ? err.name : 'error';
+            throw new AppsCloudError(502, C.ERROR_CODES.NETWORK, `Could not reach Crewly Apps (${why}). Try again shortly.`);
+        }
+    }
+}
+//# sourceMappingURL=apps-cloud.client.js.map

package/dist/backend/backend/src/services/apps/apps-cloud.client.js.map

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

package/dist/backend/backend/src/services/apps/apps-registry.service.d.ts

@@ -0,0 +1,107 @@
+/**
+ * AppsRegistryService — the apps this instance published, kept in
+ * `<CREWLY_HOME>/apps/registry.json`.
+ *
+ * It answers two questions: which app an agent's publish goes to (so the
+ * same agent republishing the same directory lands on the same app), and
+ * which agent to wake when an app changes. It also keeps each app's change
+ * cursor for the poller (specs/2026-10-04-crewly-apps-p2.md §2, §5).
+ *
+ * @module services/apps/apps-registry.service
+ */
+/** One app this instance published. */
+export interface AppRegistryEntry {
+    appId: string;
+    name: string;
+    url: string;
+    /** The agent woken for this app's changes (the last publisher); null = orchestrator */
+    agentSession: string | null;
+    /** Absolute source directory or file it was published from */
+    source: string | null;
+    currentVersion: number | null;
+    /** Last change seq handled by the poller; null until it first reads the head */
+    cursor: number | null;
+    createdAt: string;
+    updatedAt: string;
+    /** Gone from Cloud (404): no longer polled */
+    deleted?: boolean;
+    /** Last successful wake per recipient (session, or the orchestrator key), epoch ms: the cooldown survives a restart */
+    wakes?: Record<string, number>;
+    /** Seqs above `cursor` already delivered (another batch for this app is still pending): skipped when re-read */
+    delivered?: number[];
+}
+/** What to look an app up by when publishing. */
+export interface AppLookup {
+    appId?: string;
+    agentSession?: string | null;
+    source?: string | null;
+    name?: string | null;
+}
+/**
+ * File-backed registry. All writes are serialised in-process.
+ */
+export declare class AppsRegistryService {
+    private readonly file;
+    private data;
+    private chain;
+    /**
+     * @param crewlyHome - CREWLY_HOME directory
+     */
+    constructor(crewlyHome: string);
+    private load;
+    private mutate;
+    /**
+     * Every app, deleted ones included.
+     *
+     * @returns Copies of the entries
+     */
+    list(): Promise<AppRegistryEntry[]>;
+    /**
+     * One app by id.
+     *
+     * @param appId - App id
+     * @returns A copy, or null
+     */
+    get(appId: string): Promise<AppRegistryEntry | null>;
+    /**
+     * The app a publish should go to: explicit id; else the same agent and
+     * source; else the same agent and name (case-insensitive). Deleted apps
+     * never match implicitly.
+     *
+     * @param q - Lookup keys
+     * @returns The entry, or null (create a new app)
+     */
+    find(q: AppLookup): Promise<AppRegistryEntry | null>;
+    /**
+     * Insert or update an entry (fields given replace the stored ones).
+     *
+     * @param appId - App id
+     * @param patch - Fields to set
+     * @returns The stored entry
+     */
+    upsert(appId: string, patch: Partial<Omit<AppRegistryEntry, 'appId'>>): Promise<AppRegistryEntry>;
+    /**
+     * Store the poller's progress: the cursor and the seqs above it that were
+     * already delivered (no-op for an unknown app or no change).
+     *
+     * @param appId - App id
+     * @param cursor - Safe cursor (before every undelivered change)
+     * @param delivered - Delivered seqs above the cursor
+     */
+    setProgress(appId: string, cursor: number, delivered: number[]): Promise<void>;
+    /**
+     * Record a successful wake for the cooldown.
+     *
+     * @param appId - App id
+     * @param recipient - Session or orchestrator key
+     * @param at - Epoch ms
+     */
+    setLastWake(appId: string, recipient: string, at: number): Promise<void>;
+    /**
+     * Mark an app gone from Cloud.
+     *
+     * @param appId - App id
+     */
+    markDeleted(appId: string): Promise<void>;
+}
+//# sourceMappingURL=apps-registry.service.d.ts.map