@homespunapps/core 1.6.53 → 1.6.55

package/dist/app-stream.d.ts

@@ -75,5 +75,95 @@ export interface AppStreamHandle {
  * `truncated:true`) so callers only handle individual entries.
  */
 export declare function openAppStream(opts: OpenAppStreamOptions, handlers: AppStreamHandlers): AppStreamHandle;
+export interface OpenWorkerStreamOptions {
+    /**
+     * The relay's API base, e.g. `https://app.homespun.dev` — NOT an app origin, and
+     * NOT a WebSocket URL. The path is appended here so a caller cannot get it wrong,
+     * which the per-app version demonstrated was worth taking out of their hands.
+     */
+    baseUrl: string;
+    /** Agent API key, carried via the `homespun.agentkey.<key>` subprotocol token. */
+    apiKey: string;
+}
+export interface WorkerStreamHandlers {
+    /**
+     * Fired once on connect.
+     *
+     * `push` is the relay telling the worker whether offering credit will achieve
+     * anything. A worker that promised its capacity to a relay with push switched off
+     * would hold that capacity back from its own polling and starve waiting for frames
+     * that are never coming, so this is answered rather than inferred. An older relay
+     * omits it, and `false` is the safe reading: poll.
+     */
+    onHello?: (info: {
+        push: boolean;
+    }) => void;
+    /**
+     * A task was queued for one of this owner's apps. `appId` is present so a worker
+     * can narrow its claim, and is the ONLY thing the frame carries: no task id, no
+     * prompt, no row data. A consumer that never receives one (no socket, dropped
+     * frame, older relay) must still poll and lose nothing but time.
+     */
+    onAgentTaskAvailable?: (info: {
+        appId: string;
+    }) => void;
+    /**
+     * A task has been ASSIGNED to this worker: leased, with the whole envelope.
+     *
+     * Unlike the hint above, this is work in hand. The lease is already running, so a
+     * consumer that ignores the frame holds a task nobody is doing until the lease lapses.
+     * The envelope is the same shape the claim route returns, deliberately, so a consumer
+     * can hand it to the same executor either way.
+     */
+    onAssign?: (envelope: WorkerTaskEnvelope) => void;
+    /** Fired when the socket closes (cleanly or otherwise). */
+    onClose?: (info: {
+        code: number;
+        reason: string;
+    }) => void;
+    /** Fired on a transport-level error, including a rejected upgrade. */
+    onError?: (err: Error) => void;
+}
+/**
+ * One assigned task, as the relay sends it.
+ *
+ * Kept OPEN (`[k: string]: unknown`) on purpose. This client does not interpret the
+ * envelope, it forwards it, and a closed type here would silently drop any field the
+ * relay adds later: a consumer piping the whole object to a child process would start
+ * handing over a truncated version of it after a relay upgrade. Only the fields this
+ * layer actually reasons about are named.
+ */
+export interface WorkerTaskEnvelope {
+    task_id: string;
+    app_id: string;
+    app_slug: string;
+    task_type: string;
+    [k: string]: unknown;
+}
+/** A live worker stream, with the client-to-server half of the protocol. */
+export interface WorkerStreamHandle extends AppStreamHandle {
+    /**
+     * Declare how many tasks this worker will accept, right now.
+     *
+     * ABSOLUTE, not an increment: the relay replaces whatever it held. Send it again after
+     * each task finishes to top back up. The worker has to drive this, because an ack goes
+     * over HTTP to whichever replica answers and that is usually not the one holding this
+     * socket, so the relay cannot see a task finish.
+     *
+     * Returns false if the socket was not open, so a caller can tell the difference
+     * between "declared" and "shouted into a closed pipe".
+     */
+    sendReady(credits: number): boolean;
+}
+/** Derive the worker stream's WebSocket URL from an API base (https -> wss). */
+export declare function workerWsUrlFromBase(baseUrl: string): string;
+/**
+ * Open the worker stream: one socket, wakes for every app this key's owner has.
+ *
+ * Does not reconnect. That is the caller's job, because only the caller knows whether
+ * an outage is worth announcing and the CLI already has the backoff-with-one-warning
+ * behaviour this would otherwise duplicate.
+ */
+export declare function openWorkerStream(opts: OpenWorkerStreamOptions, handlers: WorkerStreamHandlers): WorkerStreamHandle;
 /** Derive an app's `/_hs/ws` URL from its `url` field (https -> wss). */
 export declare function appWsUrlFromAppUrl(appUrl: string): string;

package/dist/app-stream.js

@@ -128,6 +128,112 @@ export function openAppStream(opts, handlers) {
         },
     };
 }
+/** Derive the worker stream's WebSocket URL from an API base (https -> wss). */
+export function workerWsUrlFromBase(baseUrl) {
+    const u = new URL(baseUrl);
+    u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
+    u.pathname = u.pathname.replace(/\/$/, "") + "/v1/agent-tasks/stream";
+    u.search = "";
+    u.hash = "";
+    return u.toString();
+}
+/**
+ * Open the worker stream: one socket, wakes for every app this key's owner has.
+ *
+ * Does not reconnect. That is the caller's job, because only the caller knows whether
+ * an outage is worth announcing and the CLI already has the backoff-with-one-warning
+ * behaviour this would otherwise duplicate.
+ */
+export function openWorkerStream(opts, handlers) {
+    const socket = new WebSocket(workerWsUrlFromBase(opts.baseUrl), [
+        "homespun.v1",
+        `homespun.agentkey.${opts.apiKey}`,
+    ]);
+    socket.on("message", (raw) => {
+        let msg;
+        try {
+            msg = JSON.parse(raw.toString());
+        }
+        catch (e) {
+            handlers.onError?.(new Error(`failed to parse worker stream frame as JSON: ${e instanceof Error ? e.message : String(e)}`));
+            return;
+        }
+        if (!msg || typeof msg !== "object") {
+            handlers.onError?.(new Error("unexpected non-object worker stream frame"));
+            return;
+        }
+        const obj = msg;
+        switch (obj["type"]) {
+            case "hello":
+                handlers.onHello?.({ push: obj["push"] === true });
+                return;
+            case "agent-task.available": {
+                const appId = obj["app_id"];
+                // A wake with no app id is not passed on as a wake for app "". The worker
+                // would claim with an empty filter and either drain apps it was told not to
+                // or claim nothing at all, and both are worse than reporting a bad frame.
+                if (typeof appId !== "string" || appId === "") {
+                    handlers.onError?.(new Error("worker stream wake frame carried no app_id"));
+                    return;
+                }
+                handlers.onAgentTaskAvailable?.({ appId });
+                return;
+            }
+            case "agent-task.assign": {
+                // Validated harder than the hint, because this frame is WORK rather than a
+                // suggestion. A leased task the consumer cannot identify is a task nobody will
+                // ack, and it stays out of circulation for a whole lease before anyone notices.
+                const taskId = obj["task_id"];
+                if (typeof taskId !== "string" || taskId === "") {
+                    handlers.onError?.(new Error("worker stream assign frame carried no task_id"));
+                    return;
+                }
+                // `type` is stripped: it is this protocol's envelope tag, not part of the task,
+                // and leaving it in would put a field in a consumer's stdin that the claim route
+                // never sends. The two paths must hand over the same object.
+                const envelope = { ...obj };
+                delete envelope["type"];
+                handlers.onAssign?.(envelope);
+                return;
+            }
+            default:
+                // Tolerated, not an error. A newer relay may add a frame type, and a worker
+                // that treated one as a fault would report an outage every time the relay
+                // gained a feature. Unknown frames are simply not wakes.
+                return;
+        }
+    });
+    socket.on("close", (code, reason) => {
+        handlers.onClose?.({ code, reason: reason.toString() });
+    });
+    socket.on("error", (err) => {
+        handlers.onError?.(err instanceof Error ? err : new Error(String(err)));
+    });
+    return {
+        close() {
+            try {
+                socket.close();
+            }
+            catch {
+                /* already closing */
+            }
+        },
+        sendReady(credits) {
+            if (socket.readyState !== WebSocket.OPEN)
+                return false;
+            try {
+                socket.send(JSON.stringify({ type: "ready", credits }));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        get socket() {
+            return socket;
+        },
+    };
+}
 /** Derive an app's `/_hs/ws` URL from its `url` field (https -> wss). */
 export function appWsUrlFromAppUrl(appUrl) {
     const u = new URL(appUrl);

package/dist/client.d.ts

@@ -318,6 +318,20 @@ export declare class HomespunClient {
         cursor?: string;
         slug?: string;
     }): Promise<AppsPage>;
+    /**
+     * GET /v1/apps/advisories — the owner security audit.
+     *
+     * Every security advisory the caller's OWN live apps earn, computed from
+     * their stored manifests rather than at deploy time. That is the point: a
+     * deploy-time warning only ever reaches an app that redeploys, so an app
+     * deployed once and never touched keeps its shape forever with nobody told.
+     *
+     * Read-only. It never changes an app; the repair is one redeploy per app,
+     * and the correct fix genuinely differs per app.
+     */
+    appAdvisories(opts?: {
+        severity?: "high" | "medium" | "low";
+    }): Promise<AppAdvisoriesReport>;
     /** GET /v1/apps/:id — full app detail (manifest, current_version, quota). */
     getApp(appId: string): Promise<AppDetail>;
     /**
@@ -1052,6 +1066,44 @@ export interface AppsPage {
     items: AppSummary[];
     next_cursor: string | null;
 }
+/** One security finding against a collection's declared permission shape. */
+export interface CollectionAdvisory {
+    /** Stable identifier, safe to filter and count on. */
+    code: string;
+    collection: string;
+    /**
+     * `high` = exploitable by an anonymous caller today, with no precondition
+     * beyond opening the app. `medium` = a real weakness that needs something
+     * else to go wrong first. `low` = a design smell, frequently intentional.
+     */
+    severity: "high" | "medium" | "low";
+    message: string;
+}
+/** One app's findings, from `GET /v1/apps/advisories`. */
+export interface AppAdvisories {
+    app_id: string;
+    slug: string;
+    visibility: "private" | "link" | "public";
+    status: string;
+    current_version: number;
+    highest_severity: "high" | "medium" | "low";
+    advisories: CollectionAdvisory[];
+}
+/** `GET /v1/apps/advisories`: the owner security audit across every owned app. */
+export interface AppAdvisoriesReport {
+    /** Live apps considered, including those with nothing to report. */
+    apps_scanned: number;
+    apps_affected: number;
+    /** Counts across the WHOLE audit, unaffected by any `severity` filter. */
+    counts: {
+        high: number;
+        medium: number;
+        low: number;
+    };
+    /** True when a cap stopped the walk before the owner's apps ran out. */
+    truncated: boolean;
+    items: AppAdvisories[];
+}
 /** `GET /v1/apps/:id/document`: an app's authored HTML source (current version). */
 export interface AppDocument {
     /** The authored HTML, exactly as deployed (no served-page prelude injected). */

package/dist/client.js

@@ -610,6 +610,27 @@ export class HomespunClient {
             this.fail(r);
         return this.asObject(r);
     }
+    /**
+     * GET /v1/apps/advisories — the owner security audit.
+     *
+     * Every security advisory the caller's OWN live apps earn, computed from
+     * their stored manifests rather than at deploy time. That is the point: a
+     * deploy-time warning only ever reaches an app that redeploys, so an app
+     * deployed once and never touched keeps its shape forever with nobody told.
+     *
+     * Read-only. It never changes an app; the repair is one redeploy per app,
+     * and the correct fix genuinely differs per app.
+     */
+    async appAdvisories(opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.severity !== undefined)
+            q.set("severity", opts.severity);
+        const qs = q.toString();
+        const r = await this.call("GET", `/v1/apps/advisories${qs ? "?" + qs : ""}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
     /** GET /v1/apps/:id — full app detail (manifest, current_version, quota). */
     async getApp(appId) {
         const r = await this.call("GET", `/v1/apps/${encodeURIComponent(appId)}`);

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { openStream } from "./stream.js";
 export type { OpenStreamOptions, StreamHandlers, StreamHandle, } from "./stream.js";
 export { openAppStream, appWsUrlFromAppUrl } from "./app-stream.js";
 export type { OpenAppStreamOptions, AppStreamHandlers, AppStreamHandle, } from "./app-stream.js";
+export { openWorkerStream, workerWsUrlFromBase } from "./app-stream.js";
+export type { OpenWorkerStreamOptions, WorkerStreamHandlers, WorkerStreamHandle, WorkerTaskEnvelope, } from "./app-stream.js";
 export { registerAgent } from "./register.js";
 export type { RegisterAgentOptions, RegisterAgentResult } from "./register.js";
 export { feedbackTypeSchema, submitFeedbackSchema } from "./schemas.js";

package/dist/index.js

@@ -3,6 +3,7 @@
 export { HomespunClient, HomespunApiError } from "./client.js";
 export { openStream } from "./stream.js";
 export { openAppStream, appWsUrlFromAppUrl } from "./app-stream.js";
+export { openWorkerStream, workerWsUrlFromBase } from "./app-stream.js";
 export { registerAgent } from "./register.js";
 export { feedbackTypeSchema, submitFeedbackSchema } from "./schemas.js";
 export { RELAY_FAILURE_REPORT_HINT } from "./feedback-prompt.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/core",
-  "version": "1.6.53",
+  "version": "1.6.55",
   "description": "Homespun relay client: typed HTTP + WebSocket operations against a Homespun relay. Framework-free.",
   "license": "MIT",
   "type": "module",