@beeos-ai/device-agent 0.4.3 → 0.5.1

package/dist/resources/telemetry.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Resource Resolution Layer — telemetry shim.
+ *
+ * The device-agent already ships a structured pino logger (see
+ * `logger/index.ts`). We deliberately do NOT pull in `prom-client` to
+ * keep the bundle small; instead we emit one structured log event per
+ * resolution outcome that an external Promtail / Vector pipeline can
+ * count + histogram.
+ *
+ * Event shape (counter-friendly):
+ *
+ *     {
+ *       service: "device-agent",
+ *       event:   "resource.resolution",
+ *       outcome: "success" | "fetch_error" | …,
+ *       mime:    "image/jpeg" | …,
+ *       sizeBytes: number,
+ *       durationMs: number,
+ *       sourceUrl: "https://example.com/x.jpg"
+ *     }
+ *
+ * The outcome label vocabulary is closed (see `ResolveOutcomeLabel` in
+ * `types.ts`) so a Prometheus exporter can rely on bounded cardinality.
+ *
+ * All entry points accept any pino-like logger so unit tests can pass
+ * a minimal stub.
+ */
+import type { ResolveOutcomeLabel } from "./types.js";
+export interface TelemetryLogger {
+    info(obj: Record<string, unknown>, msg?: string): void;
+    warn(obj: Record<string, unknown>, msg?: string): void;
+}
+export interface RecordResolutionOpts {
+    outcome: ResolveOutcomeLabel;
+    mime?: string;
+    sizeBytes?: number;
+    durationMs: number;
+    sourceUrl?: string;
+    /** Free-form error message for failed outcomes (NOT a counter label). */
+    error?: string;
+}
+/**
+ * Emit one structured log line corresponding to a single resolution
+ * outcome. The downstream log pipeline aggregates these into:
+ *
+ *   - counter `device_agent_resource_resolution_total{outcome,mime}`
+ *   - histogram `device_agent_resource_resolution_duration_ms{mime}`
+ *
+ * The `event` field is kept stable (`resource.resolution`) so log-based
+ * counters don't drift across versions.
+ */
+export declare function recordResolution(log: TelemetryLogger, opts: RecordResolutionOpts): void;

package/dist/resources/telemetry.js

@@ -0,0 +1,59 @@
+/**
+ * Resource Resolution Layer — telemetry shim.
+ *
+ * The device-agent already ships a structured pino logger (see
+ * `logger/index.ts`). We deliberately do NOT pull in `prom-client` to
+ * keep the bundle small; instead we emit one structured log event per
+ * resolution outcome that an external Promtail / Vector pipeline can
+ * count + histogram.
+ *
+ * Event shape (counter-friendly):
+ *
+ *     {
+ *       service: "device-agent",
+ *       event:   "resource.resolution",
+ *       outcome: "success" | "fetch_error" | …,
+ *       mime:    "image/jpeg" | …,
+ *       sizeBytes: number,
+ *       durationMs: number,
+ *       sourceUrl: "https://example.com/x.jpg"
+ *     }
+ *
+ * The outcome label vocabulary is closed (see `ResolveOutcomeLabel` in
+ * `types.ts`) so a Prometheus exporter can rely on bounded cardinality.
+ *
+ * All entry points accept any pino-like logger so unit tests can pass
+ * a minimal stub.
+ */
+/**
+ * Emit one structured log line corresponding to a single resolution
+ * outcome. The downstream log pipeline aggregates these into:
+ *
+ *   - counter `device_agent_resource_resolution_total{outcome,mime}`
+ *   - histogram `device_agent_resource_resolution_duration_ms{mime}`
+ *
+ * The `event` field is kept stable (`resource.resolution`) so log-based
+ * counters don't drift across versions.
+ */
+export function recordResolution(log, opts) {
+    const fields = {
+        event: "resource.resolution",
+        outcome: opts.outcome,
+        durationMs: opts.durationMs,
+    };
+    if (opts.mime)
+        fields.mime = opts.mime;
+    if (opts.sizeBytes !== undefined)
+        fields.sizeBytes = opts.sizeBytes;
+    if (opts.sourceUrl)
+        fields.sourceUrl = opts.sourceUrl;
+    if (opts.error)
+        fields.error = opts.error;
+    if (opts.outcome === "success" || opts.outcome === "cache_hit") {
+        log.info(fields, "resource.resolution");
+    }
+    else {
+        log.warn(fields, "resource.resolution");
+    }
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/resources/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/resources/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAmBH;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAoB,EACpB,IAA0B;IAE1B,MAAM,MAAM,GAA4B;QACtC,KAAK,EAAE,qBAAqB;QAC5B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,UAAU,EAAE,IAAI,CAAC,UAAU;KAC5B,CAAC;IACF,IAAI,IAAI,CAAC,IAAI;QAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACvC,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;QAAE,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACpE,IAAI,IAAI,CAAC,SAAS;QAAE,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACtD,IAAI,IAAI,CAAC,KAAK;QAAE,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1C,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,WAAW,EAAE,CAAC;QAC/D,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAC1C,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC"}

package/dist/resources/types.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Resource Resolution Layer — type contracts.
+ *
+ * Background: AutoGLM-Phone-9B (and other open-source mobile VLMs we ship)
+ * are pure-vision agents — they cannot fetch URLs, write files, or run
+ * shell commands. When a user task references a non-visual resource
+ * (image URL, video URL, PDF, APK), the prompt has to be **resolved**
+ * to a device-local path before the VLM ever sees it. This module
+ * defines the protocol for that resolution.
+ *
+ * Architectural seam: this layer runs inside `AgentHost.submitTask`,
+ * BEFORE `IAgentCore.run` is called and AFTER `task:start` has been
+ * emitted (so cancel-mid-resolution works). Concrete resolvers
+ * consume an `IDevice` (for `resolveWellKnownDir(mime)`) and an
+ * `IMcpRuntime` (for `file_write` / `execute_command`) without
+ * importing them directly — both are passed in via `ResolverContext`.
+ *
+ * Industry references that shaped this design:
+ *   - MAS-Bench (arxiv 2509.06477v2): "GUI-Shortcut Hybrid Paradigm"
+ *     — establishes that non-GUI resource preparation is a first-class
+ *     orthogonal concern to GUI execution.
+ *   - Anthropic Computer Use: tool-calling LLMs treat `bash` and
+ *     `computer` symmetrically; we mirror that by treating
+ *     `resolve_resource` as a real, observable tool event.
+ *   - droidrun / mobilerun's `AndroidDriver`: GUI-only — confirms our
+ *     gap analysis.
+ */
+import type { IDevice } from "../ports/device.js";
+import type { IMcpRuntime } from "../mcp-client/runtime.js";
+/**
+ * A reference to a resource the agent task mentions but cannot consume
+ * directly. Discriminated union so we can grow the surface (file://,
+ * embedded base64 blob, RFC 3986 data URLs, geo coordinates) without
+ * breaking existing resolvers.
+ *
+ * Phase 1 implements `url` only; the others are typed placeholders so
+ * unit tests can pin the shape and downstream code can pattern-match
+ * exhaustively now (TS compiler will surface any addition).
+ */
+export type ResourceRef = {
+    kind: "url";
+    url: string;
+} | {
+    kind: "file";
+    path: string;
+} | {
+    kind: "text";
+    text: string;
+} | {
+    kind: "coordinate";
+    lat: number;
+    lon: number;
+}
+/**
+ * BeeOS-uploaded file ref. The web UI emits ACP `resource_link` blocks
+ * with a `beeos-file://<fileId>` URI for every attachment the user
+ * uploads via the chat input. The `BeeosFileResolver` exchanges the
+ * fileId for a short-lived presigned download URL via the Agent
+ * Gateway and then delegates the actual fetch/push to the same
+ * pipeline used by `UrlResolver`. `hintMime` / `hintName` are the
+ * client-supplied metadata from the `resource_link` block; the
+ * resolver still treats the server's `Content-Type` as authoritative.
+ */
+ | {
+    kind: "beeos-file";
+    fileId: string;
+    hintMime?: string;
+    hintName?: string;
+};
+/**
+ * What the resolver returns and what the augmenter consumes.
+ *
+ * Stable contract: every successful resolution MUST populate every
+ * required field. `scannedToMediaStore` is platform-specific (Android
+ * media-scanner) and is allowed to be `false` on platforms where the
+ * concept does not exist (desktop) — that does NOT count as a failure.
+ */
+export interface ResolvedAsset {
+    /** Source ref (echoed back so the augmenter can render the URL). */
+    ref: ResourceRef;
+    /** Device-local absolute path (e.g. `/sdcard/Pictures/beeos_…jpg`). */
+    remotePath: string;
+    /** Validated content type (image/jpeg, video/mp4, …). */
+    mime: string;
+    /** Bytes written to the device. */
+    sizeBytes: number;
+    /** SHA-256 of the resource bytes (lowercase hex). */
+    sha256: string;
+    /** True iff the platform supports + acknowledged a media-scan trigger. */
+    scannedToMediaStore: boolean;
+    /** Echo of the original URL for `url` refs (empty for non-url refs). */
+    sourceUrl: string;
+    /** When the resolution completed (ms since epoch, host clock). */
+    resolvedAt: number;
+}
+/**
+ * Side-effects + capabilities a resolver may consume. The host owns
+ * construction so resolvers stay testable without spinning up a real
+ * MCP server or device.
+ */
+export interface ResolverContext {
+    /** Active device — for `resolveWellKnownDir(mime)`. */
+    readonly device: IDevice;
+    /** Active MCP runtime — for `file_write` / `execute_command`. */
+    readonly mcp: IMcpRuntime;
+    /** Merge-cancel signal (host's controller + caller's signal). */
+    readonly abortSignal: AbortSignal;
+    /** Hard cap on bytes per resource. Resolvers MUST honor this. */
+    readonly maxBytes: number;
+    /** Per-resolve fetch / push timeout. Resolvers MUST honor this. */
+    readonly timeoutMs: number;
+    /** Allow-listed URL schemes (`["http", "https"]` in production). */
+    readonly allowedSchemes: readonly string[];
+    /** Whether to reject RFC1918 / loopback / link-local IPs. */
+    readonly denyPrivateIp: boolean;
+    /**
+     * Optional emitter for fine-grained progress events. Resolvers
+     * SHOULD call this during long downloads (start, periodic update,
+     * end) so the AgentHost can surface them as `task:tool` updates.
+     */
+    readonly emitProgress?: (ev: ResolveProgressEvent) => void;
+    /** Structured logger (correlation-aware). */
+    readonly log: ResolverLogger;
+    /**
+     * Optional disk-pressure guard (Phase 1.5 / lifecycle L3). When
+     * present, the resolver calls `assertCapacity(...)` immediately
+     * before `mcp.fileWrite`; the guard may free space via a force-
+     * sweep or reject the resolve with `disk_pressure`. When absent
+     * (tests, lab, or `lifecycle.mode=off`), the resolver behaves
+     * exactly as it did pre-1.5.
+     */
+    readonly diskPressure?: DiskPressureGuard;
+}
+/**
+ * Phase 1.5 disk-pressure guard contract — declared here (alongside
+ * `ResolverContext`) so the resolver and the lifecycle module share
+ * a single source of truth without `lifecycle/*` having to import
+ * resolver internals.
+ *
+ * Implementation lives at `resources/lifecycle/disk-pressure.ts`.
+ */
+export interface DiskPressureGuard {
+    /**
+     * Inspect available space on the sandbox volume and either:
+     *   1. return silently (free space is comfortable),
+     *   2. trigger a force-sweep and return silently (now there's room), or
+     *   3. throw a `ResolverError("disk_pressure", ...)` (still tight
+     *      after sweeping) so the resolver fails fast and the host
+     *      records a structured outcome.
+     */
+    assertCapacity(args: DiskPressureCheckArgs): Promise<void>;
+}
+export interface DiskPressureCheckArgs {
+    /** MCP runtime (`executeCommand` is required for `df`/`find`). */
+    readonly mcp: IMcpRuntime;
+    /**
+     * Sandbox directory the resolver is about to write into. Used as
+     * both the `df` target (to read the volume's free bytes) and the
+     * sweep root (to evict the oldest files when we need to free up
+     * space).
+     */
+    readonly sandboxDir: string;
+    /**
+     * Bytes the resolver is about to write. The guard treats `free -
+     * incomingBytes` as the post-write headroom estimate.
+     */
+    readonly incomingBytes: number;
+    /** Structured logger (correlation-aware). */
+    readonly log: ResolverLogger;
+}
+/**
+ * Minimal log surface — the host hands a child pino instance with the
+ * `taskId` correlation already attached. Kept generic so unit tests can
+ * pass a stub.
+ */
+export interface ResolverLogger {
+    debug(obj: Record<string, unknown>, msg?: string): void;
+    info(obj: Record<string, unknown>, msg?: string): void;
+    warn(obj: Record<string, unknown>, msg?: string): void;
+    error(obj: Record<string, unknown>, msg?: string): void;
+}
+/**
+ * Progress events for the AgentHost telemetry stream. Mapped 1:1 to
+ * `task:tool` events with `name = "resolve_resource"` and lifecycle
+ * `start | update | end`.
+ */
+export type ResolveProgressEvent = {
+    phase: "start";
+    ref: ResourceRef;
+} | {
+    phase: "update";
+    ref: ResourceRef;
+    downloadedBytes: number;
+    totalBytes?: number;
+} | {
+    phase: "end";
+    ref: ResourceRef;
+    asset?: ResolvedAsset;
+    error?: Error;
+};
+/**
+ * Resolver port — every concrete resolver (URL, file://, …) implements
+ * this interface. `match` is intentionally separate from `resolve` so
+ * the registry can dispatch without invoking side effects.
+ */
+export interface ResourceResolver {
+    /** Free-form name for logging / metrics ("url", "file", …). */
+    readonly name: string;
+    /** Cheap predicate: does this resolver own the supplied ref? */
+    match(ref: ResourceRef): boolean;
+    /** Heavy work: download / push / scan. Throws on failure. */
+    resolve(ref: ResourceRef, ctx: ResolverContext): Promise<ResolvedAsset>;
+}
+/**
+ * Parser port — extracts `ResourceRef`s from a free-form task string.
+ * The host iterates every registered parser and unions the results.
+ *
+ * Phase 1 ships a single `UrlParser` that finds http(s) URLs anywhere
+ * in the task. Future parsers may extract `file://` paths, base64
+ * data URLs, or geo coordinates.
+ */
+export interface ResourceParser {
+    readonly name: string;
+    parse(task: string): ResourceRef[];
+}
+/**
+ * Augmenter port — turns the original task + the list of resolved
+ * assets into the final string we hand to `IAgentCore.run`.
+ *
+ * Implementations MUST:
+ *  - preserve the original task verbatim (the VLM's reasoning depends
+ *    on the human-supplied wording).
+ *  - state the source-URL ↔ device-path identity so the agent never
+ *    confuses two visually similar resources.
+ *  - NOT prescribe any GUI path (no "tap the first photo" hints —
+ *    that's the VLM's job).
+ */
+export interface TaskContextAugmenter {
+    augment(originalTask: string, assets: readonly ResolvedAsset[]): string;
+}
+/**
+ * Telemetry label for the resource-resolution counter. Kept here so
+ * adapters and tests reference one symbolic source of truth.
+ *
+ * Why an enum-like type union instead of a free-form string: Prometheus
+ * cardinality discipline. We must not let arbitrary error strings leak
+ * into label values.
+ */
+export type ResolveOutcomeLabel = "success" | "fetch_error" | "push_error" | "scanner_failed" | "disallowed_scheme" | "oversized" | "timeout" | "private_ip_blocked" | "dns_rebind_blocked" | "disallowed_mime" | "disk_pressure" | "cache_hit" | "cache_validation_miss" | "aborted";

package/dist/resources/types.js

@@ -0,0 +1,29 @@
+/**
+ * Resource Resolution Layer — type contracts.
+ *
+ * Background: AutoGLM-Phone-9B (and other open-source mobile VLMs we ship)
+ * are pure-vision agents — they cannot fetch URLs, write files, or run
+ * shell commands. When a user task references a non-visual resource
+ * (image URL, video URL, PDF, APK), the prompt has to be **resolved**
+ * to a device-local path before the VLM ever sees it. This module
+ * defines the protocol for that resolution.
+ *
+ * Architectural seam: this layer runs inside `AgentHost.submitTask`,
+ * BEFORE `IAgentCore.run` is called and AFTER `task:start` has been
+ * emitted (so cancel-mid-resolution works). Concrete resolvers
+ * consume an `IDevice` (for `resolveWellKnownDir(mime)`) and an
+ * `IMcpRuntime` (for `file_write` / `execute_command`) without
+ * importing them directly — both are passed in via `ResolverContext`.
+ *
+ * Industry references that shaped this design:
+ *   - MAS-Bench (arxiv 2509.06477v2): "GUI-Shortcut Hybrid Paradigm"
+ *     — establishes that non-GUI resource preparation is a first-class
+ *     orthogonal concern to GUI execution.
+ *   - Anthropic Computer Use: tool-calling LLMs treat `bash` and
+ *     `computer` symmetrically; we mirror that by treating
+ *     `resolve_resource` as a real, observable tool event.
+ *   - droidrun / mobilerun's `AndroidDriver`: GUI-only — confirms our
+ *     gap analysis.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/resources/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/resources/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

package/dist/shortcuts/builtins/download-to-device.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Shortcut: `download_to_device`
+ *
+ * Download an HTTP(S) URL onto the connected device using the same
+ * `ResourceResolver` backend that the AgentHost auto-trigger
+ * (Phase 1) uses.
+ *
+ * Why a *second* entry point for the resolver:
+ *
+ *   D8 — phase 1 wires resolution into `AgentHost.submitTask` so the
+ *   *initial* prompt's URLs are pre-fetched before the VLM ever sees
+ *   them. But the orchestrator may also encounter URLs **mid-task**:
+ *
+ *     - the user attaches a follow-up message with another image
+ *     - the GUI flow asks the agent to copy a link the agent just
+ *       extracted from a screen
+ *     - a shortcut chain (`open_deeplink → screenshot → ...`) needs
+ *       to refer to the resolved file path
+ *
+ *   Without `download_to_device`, the LLM would be stuck — it has no
+ *   `bash` and no `file_write`. The shortcut closes that gap by
+ *   exposing the same resolver under an LLM-callable name. Both
+ *   call sites share the **same** `ResourceResolutionCache` so a
+ *   download primed by either path is reused by the other. (The
+ *   bootstrap wires the `ShortcutResourceFacade` against the same
+ *   registry instance the `AgentHostImpl` holds — see
+ *   `bootstrap.ts`.)
+ *
+ * Design constraints:
+ *
+ *   - No LLM-visible flag for SSRF / size cap / timeout — they all
+ *     come from the same env-var feature flags as the auto path
+ *     (`RESOURCE_RESOLUTION_*`), so the security posture is identical
+ *     across both surfaces. The LLM cannot weaken it.
+ *   - No `mime` / `path` knob: the resolver picks the well-known dir
+ *     by Content-Type. Letting the LLM pick a destination would be a
+ *     path-traversal hazard.
+ *
+ * Failure mapping:
+ *
+ *   - The underlying resolver throws `ResolverError` with codes from
+ *     `ResolverErrorCode`. We translate them into shortcut-error
+ *     codes the orchestrator already understands. See
+ *     `mapResolverError`.
+ *
+ * Platform: any (image / video / audio / document downloads work on
+ * desktop too; APK is rejected by `IDevice.resolveWellKnownDir` on
+ * desktop with `unsupported_platform`).
+ */
+import type { Shortcut, ShortcutContext, ShortcutResult } from "../types.js";
+interface DownloadArgs {
+    url: string;
+}
+interface DownloadOutput {
+    remotePath: string;
+    mime: string;
+    sizeBytes: number;
+    sha256: string;
+    sourceUrl: string;
+}
+export declare class DownloadToDeviceShortcut implements Shortcut<DownloadArgs, DownloadOutput> {
+    readonly descriptor: {
+        id: string;
+        displayName: string;
+        description: string;
+        jsonSchema: {
+            type: string;
+            properties: {
+                url: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+            additionalProperties: boolean;
+        };
+        kind: "api";
+        platforms: readonly ["any"];
+        timeoutMs: number;
+    };
+    execute(args: DownloadArgs, ctx: ShortcutContext): Promise<ShortcutResult<DownloadOutput>>;
+}
+export {};

package/dist/shortcuts/builtins/download-to-device.js

@@ -0,0 +1,125 @@
+/**
+ * Shortcut: `download_to_device`
+ *
+ * Download an HTTP(S) URL onto the connected device using the same
+ * `ResourceResolver` backend that the AgentHost auto-trigger
+ * (Phase 1) uses.
+ *
+ * Why a *second* entry point for the resolver:
+ *
+ *   D8 — phase 1 wires resolution into `AgentHost.submitTask` so the
+ *   *initial* prompt's URLs are pre-fetched before the VLM ever sees
+ *   them. But the orchestrator may also encounter URLs **mid-task**:
+ *
+ *     - the user attaches a follow-up message with another image
+ *     - the GUI flow asks the agent to copy a link the agent just
+ *       extracted from a screen
+ *     - a shortcut chain (`open_deeplink → screenshot → ...`) needs
+ *       to refer to the resolved file path
+ *
+ *   Without `download_to_device`, the LLM would be stuck — it has no
+ *   `bash` and no `file_write`. The shortcut closes that gap by
+ *   exposing the same resolver under an LLM-callable name. Both
+ *   call sites share the **same** `ResourceResolutionCache` so a
+ *   download primed by either path is reused by the other. (The
+ *   bootstrap wires the `ShortcutResourceFacade` against the same
+ *   registry instance the `AgentHostImpl` holds — see
+ *   `bootstrap.ts`.)
+ *
+ * Design constraints:
+ *
+ *   - No LLM-visible flag for SSRF / size cap / timeout — they all
+ *     come from the same env-var feature flags as the auto path
+ *     (`RESOURCE_RESOLUTION_*`), so the security posture is identical
+ *     across both surfaces. The LLM cannot weaken it.
+ *   - No `mime` / `path` knob: the resolver picks the well-known dir
+ *     by Content-Type. Letting the LLM pick a destination would be a
+ *     path-traversal hazard.
+ *
+ * Failure mapping:
+ *
+ *   - The underlying resolver throws `ResolverError` with codes from
+ *     `ResolverErrorCode`. We translate them into shortcut-error
+ *     codes the orchestrator already understands. See
+ *     `mapResolverError`.
+ *
+ * Platform: any (image / video / audio / document downloads work on
+ * desktop too; APK is rejected by `IDevice.resolveWellKnownDir` on
+ * desktop with `unsupported_platform`).
+ */
+export class DownloadToDeviceShortcut {
+    descriptor = {
+        id: "download_to_device",
+        displayName: "Download to Device",
+        description: "Fetch an HTTP(S) URL and place the resulting file on the device " +
+            "in the well-known directory matching its Content-Type (image/*→Pictures, " +
+            "video/*→Movies, audio/*→Music, application/*→Download). Returns " +
+            "the absolute device path the file was written to plus its MIME / " +
+            "size / SHA-256. Re-uses the same cache as the host-side auto " +
+            "trigger so duplicate URLs are deduplicated.",
+        jsonSchema: {
+            type: "object",
+            properties: {
+                url: {
+                    type: "string",
+                    description: "HTTPS URL to fetch (HTTP allowed for development).",
+                },
+            },
+            required: ["url"],
+            additionalProperties: false,
+        },
+        kind: "api",
+        platforms: ["any"],
+        timeoutMs: 60_000,
+    };
+    async execute(args, ctx) {
+        if (typeof args?.url !== "string" || args.url.length === 0) {
+            return { ok: false, code: "invalid_args", message: "url must be a non-empty string" };
+        }
+        if (!ctx.resources || typeof ctx.resources.resolveUrl !== "function") {
+            return {
+                ok: false,
+                code: "permission_denied",
+                message: "shortcut runtime has no resource resolver attached",
+            };
+        }
+        try {
+            const out = await ctx.resources.resolveUrl(args.url);
+            return { ok: true, output: out };
+        }
+        catch (e) {
+            return mapResolverError(e);
+        }
+    }
+}
+/**
+ * Translate `ResolverError`-shaped failures into the shortcut error
+ * vocabulary. We deliberately don't import `ResolverError` (avoids a
+ * dependency from `shortcuts/builtins` into `resources/resolvers`) —
+ * we duck-type on `code`.
+ */
+function mapResolverError(e) {
+    const err = e;
+    const code = err?.code ?? "";
+    const message = err?.message ?? String(e);
+    switch (code) {
+        case "disallowed_scheme":
+        case "disallowed_mime":
+        case "oversized":
+            return { ok: false, code: "invalid_args", message };
+        case "private_ip_blocked":
+        case "dns_rebind_blocked":
+            return { ok: false, code: "permission_denied", message };
+        case "timeout":
+        case "aborted":
+            return { ok: false, code: "timeout", message };
+        case "fetch_error":
+            return { ok: false, code: "intent_rejected", message };
+        case "push_error":
+        case "scanner_failed":
+            return { ok: false, code: "internal_error", message };
+        default:
+            return { ok: false, code: "internal_error", message };
+    }
+}
+//# sourceMappingURL=download-to-device.js.map

package/dist/shortcuts/builtins/download-to-device.js.map

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