@camstack/types 1.1.41 → 1.1.43

package/dist/addon.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-Dqd2OlRi.js");
+const require_sleep = require("./sleep-DmvEGsRg.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 exports.BaseAddon = require_sleep.BaseAddon;
 exports.DATAPLANE_SECRET_HEADER = require_sleep.DATAPLANE_SECRET_HEADER;

package/dist/addon.mjs

@@ -1,3 +1,3 @@
-import { A as parseJsonUnknown, D as asString, I as scopeKey, M as ReadinessRegistry, N as ReadinessTimeoutError, S as DeviceType, T as asJsonObject, a as viewerUiCapability, bt as EventCategory, ct as BaseAddon, ft as emitReadiness, i as deviceOpsCapability, j as DATAPLANE_SECRET_HEADER, lt as normalizeAddonInitResult, m as expandCapMethods, o as adminUiCapability, s as createDeviceProxy, t as sleep, xt as DisposerChain } from "./sleep-b4Jf2n33.mjs";
+import { A as parseJsonUnknown, D as asString, I as scopeKey, M as ReadinessRegistry, N as ReadinessTimeoutError, S as DeviceType, T as asJsonObject, a as viewerUiCapability, bt as EventCategory, ct as BaseAddon, ft as emitReadiness, i as deviceOpsCapability, j as DATAPLANE_SECRET_HEADER, lt as normalizeAddonInitResult, m as expandCapMethods, o as adminUiCapability, s as createDeviceProxy, t as sleep, xt as DisposerChain } from "./sleep-Baang_XW.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 export { BaseAddon, DATAPLANE_SECRET_HEADER, DeviceType, DisposerChain, EventCategory, ReadinessRegistry, ReadinessTimeoutError, adminUiCapability, asJsonObject, asString, createDeviceProxy, deviceOpsCapability, emitReadiness, errMsg, expandCapMethods, normalizeAddonInitResult, parseJsonUnknown, scopeKey, sleep, viewerUiCapability };

package/dist/capabilities/advanced-notifier.cap.d.ts

@@ -28,9 +28,9 @@ declare const NotificationRuleTemplateSchema: z.ZodObject<{
     body: z.ZodString;
     imageMode: z.ZodEnum<{
         none: "none";
+        full: "full";
         crop: "crop";
         annotated: "annotated";
-        full: "full";
     }>;
 }, z.core.$strip>;
 declare const NotificationRuleSchema: z.ZodObject<{
@@ -67,9 +67,9 @@ declare const NotificationRuleSchema: z.ZodObject<{
         body: z.ZodString;
         imageMode: z.ZodEnum<{
             none: "none";
+            full: "full";
             crop: "crop";
             annotated: "annotated";
-            full: "full";
         }>;
     }, z.core.$strip>>;
     priority: z.ZodEnum<{
@@ -145,9 +145,9 @@ export declare const advancedNotifierCapability: {
                     body: z.ZodString;
                     imageMode: z.ZodEnum<{
                         none: "none";
+                        full: "full";
                         crop: "crop";
                         annotated: "annotated";
-                        full: "full";
                     }>;
                 }, z.core.$strip>>;
                 priority: z.ZodEnum<{
@@ -193,9 +193,9 @@ export declare const advancedNotifierCapability: {
                     body: z.ZodString;
                     imageMode: z.ZodEnum<{
                         none: "none";
+                        full: "full";
                         crop: "crop";
                         annotated: "annotated";
-                        full: "full";
                     }>;
                 }, z.core.$strip>>;
                 priority: z.ZodEnum<{

package/dist/capabilities/face-gallery.cap.d.ts

@@ -28,6 +28,13 @@ declare const FaceInfoSchema: z.ZodObject<{
     identityName: z.ZodOptional<z.ZodString>;
     assigned: z.ZodBoolean;
     base64: z.ZodOptional<z.ZodString>;
+    faceBbox: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        w: z.ZodNumber;
+        h: z.ZodNumber;
+    }, z.core.$strip>>;
+    keyFrameMediaKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type FaceInfo = z.infer<typeof FaceInfoSchema>;
 export declare const faceGalleryCapability: {
@@ -90,6 +97,13 @@ export declare const faceGalleryCapability: {
             identityName: z.ZodOptional<z.ZodString>;
             assigned: z.ZodBoolean;
             base64: z.ZodOptional<z.ZodString>;
+            faceBbox: z.ZodOptional<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                w: z.ZodNumber;
+                h: z.ZodNumber;
+            }, z.core.$strip>>;
+            keyFrameMediaKey: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>, import("./capability-definition.js").CapabilityMethodKind>;
         readonly getFaceByTrack: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
@@ -103,6 +117,13 @@ export declare const faceGalleryCapability: {
             identityName: z.ZodOptional<z.ZodString>;
             assigned: z.ZodBoolean;
             base64: z.ZodOptional<z.ZodString>;
+            faceBbox: z.ZodOptional<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                w: z.ZodNumber;
+                h: z.ZodNumber;
+            }, z.core.$strip>>;
+            keyFrameMediaKey: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
         readonly getFaceMedia: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             faceId: z.ZodString;

package/dist/capabilities/index.d.ts

@@ -74,12 +74,12 @@ export type { NetworkAccessStatus, NetworkEndpoint } from './network-access.cap.
 export { NetworkAccessStatusSchema, NetworkEndpointSchema, networkAccessCapability, } from './network-access.cap.js';
 export { type Attachment, AttachmentMediaTypeSchema, type AttachmentMediaType, AttachmentSchema, type DiscoveredTarget, DiscoveredTargetSchema, type INotificationOutputProvider, type NotificationAction, NotificationActionSchema, type NotificationFormat, NotificationFormatSchema, NotificationSchema, type RenderedAs, RenderedAsSchema, type SendResult, SendResultSchema, type Target, type TargetKind, type TargetKindCaps, TargetKindCapsSchema, type TargetKindLevel, TargetKindLevelSchema, TargetKindSchema, TargetSchema, type TestResult, TestResultSchema, notificationOutputCapability, } from './notification-output.cap.js';
 export { type IOauthIntegrationProvider, type OauthIntegrationDescriptor, OauthIntegrationDescriptorSchema, oauthIntegrationCapability, } from './oauth-integration.cap.js';
-export { type AudioEvent, AudioEventSchema, type DetectionSource, DetectionSourceSchema, type EventKind, EventKindSchema, type IPipelineAnalyticsProvider, type MediaFile, type MediaFileKind, MediaFileSchema, type MotionEvent, MotionEventSchema, type ObjectEvent, ObjectEventSchema, pipelineAnalyticsCapability, type ScoredObjectEvent, ScoredObjectEventSchema, type Track, TrackedDetectionSchema, TrackSchema, type TrackState, TrackStateSchema, } from './pipeline-analytics.cap.js';
+export { type AudioEvent, AudioEventSchema, type DetectionSource, DetectionSourceSchema, type EventKind, EventKindSchema, type IPipelineAnalyticsProvider, type KeyEvent, KeyEventSchema, type MediaFile, type MediaFileKind, MediaFileSchema, type MotionEvent, MotionEventSchema, type ObjectEvent, ObjectEventSchema, pipelineAnalyticsCapability, type ScoredObjectEvent, ScoredObjectEventSchema, type Track, TrackedDetectionSchema, TrackSchema, type TrackState, TrackStateSchema, } from './pipeline-analytics.cap.js';
 export type { PipelineStepInputOutput, PipelineValidationIssue, PipelineValidationResult, } from './pipeline-executor.cap.js';
 export { ModelSubstitutionSchema, PipelineDefaultStepSchema, PipelineEngineChoiceSchema, PipelineRunResultBridge, PipelineStepInputSchema, PipelineValidationIssueSchema, PipelineValidationResultSchema, pipelineExecutorCapability, } from './pipeline-executor.cap.js';
 export type { CameraAssignmentStatus, CameraAudioStatus, CameraBrokerProfile, CameraBrokerStatus, CameraDecoderShm, CameraDecoderStatus, CameraDetectionPhase, CameraDetectionProvisioning, CameraDetectionProvisioningState, CameraDetectionStatus, CameraMotionStatus, CameraRecordingMode, CameraRecordingStatus, CameraSourceStatus, CameraSourceStream, CameraStatus, IngestOwner, } from './pipeline-orchestrator.cap.js';
 export { AgentLoadSummarySchema, CameraAssignmentStatusSchema, CameraAudioStatusSchema, CameraBrokerProfileSchema, CameraBrokerStatusSchema, CameraDecoderShmSchema, CameraDecoderStatusSchema, CameraDetectionPhaseSchema, CameraDetectionProvisioningSchema, CameraDetectionProvisioningStateSchema, CameraDetectionStatusSchema, CameraMotionStatusSchema, CameraRecordingModeSchema, CameraRecordingStatusSchema, CameraSourceStatusSchema, CameraSourceStreamSchema, CameraStatusSchema, CapabilityBindingsSchema, GlobalMetricsSchema, IngestOwnerSchema, PipelineAssignmentSchema, pipelineOrchestratorCapability, } from './pipeline-orchestrator.cap.js';
-export type { MotionSource, MotionSources, ReportMotionInput, RunnerFrameSource, } from './pipeline-runner.cap.js';
+export type { DetailParent, DetailResult, MotionSource, MotionSources, ReportMotionInput, RunDetailSubtreeInput, RunDetailSubtreeResult, RunnerFrameSource, } from './pipeline-runner.cap.js';
 export { MotionSourceEnum, MotionSourcesSchema, pipelineRunnerCapability, ReportMotionInputSchema, RunnerCameraConfigSchema, RunnerCameraDeviceUIFields, RunnerFrameSourceSchema, RunnerLocalLoadSchema, RunnerLocalMetricsSchema, } from './pipeline-runner.cap.js';
 export { AudioChunkInputSchema, AudioClassificationLabelSchema, AudioLevelSchema, BoundingBoxSchema, FrameInputSchema, SpatialDetectionSchema, } from './schemas/detection-shared.js';
 export { CameraMetricsSchema, CameraMetricsWithDeviceIdSchema, OrchestratorMetricsSchema, } from './schemas/orchestrator-metrics.js';

package/dist/capabilities/pipeline-analytics.cap.d.ts

@@ -82,6 +82,9 @@ declare const TrackSchema: z.ZodObject<{
         entered: "entered";
     }>;
     active: z.ZodBoolean;
+    importance: z.ZodOptional<z.ZodNumber>;
+    bestEventId: z.ZodOptional<z.ZodString>;
+    importanceReason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type Track = z.infer<typeof TrackSchema>;
 declare const MotionEventSchema: z.ZodObject<{
@@ -146,7 +149,9 @@ declare const ObjectEventSchema: z.ZodObject<{
     frameWidth: z.ZodOptional<z.ZodNumber>;
     frameHeight: z.ZodOptional<z.ZodNumber>;
     mediaKey: z.ZodOptional<z.ZodString>;
+    keyFrameMediaKey: z.ZodOptional<z.ZodString>;
     mediaUrl: z.ZodOptional<z.ZodString>;
+    importance: z.ZodOptional<z.ZodNumber>;
     id: z.ZodString;
     deviceId: z.ZodNumber;
     timestamp: z.ZodNumber;
@@ -177,6 +182,7 @@ declare const MediaFileKindEnum: z.ZodEnum<{
     fullFrameBoxed: "fullFrameBoxed";
     faceCrop: "faceCrop";
     plateCrop: "plateCrop";
+    keyFrame: "keyFrame";
 }>;
 export type MediaFileKind = z.infer<typeof MediaFileKindEnum>;
 declare const MediaFileSchema: z.ZodObject<{
@@ -191,12 +197,24 @@ declare const MediaFileSchema: z.ZodObject<{
         fullFrameBoxed: "fullFrameBoxed";
         faceCrop: "faceCrop";
         plateCrop: "plateCrop";
+        keyFrame: "keyFrame";
     }>;
     base64: z.ZodString;
     sizeBytes: z.ZodNumber;
     timestamp: z.ZodNumber;
 }, z.core.$strip>;
 export type MediaFile = z.infer<typeof MediaFileSchema>;
+declare const KeyEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    trackId: z.ZodString;
+    timestamp: z.ZodNumber;
+    className: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    importance: z.ZodNumber;
+    bestEventId: z.ZodString;
+    windowMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type KeyEvent = z.infer<typeof KeyEventSchema>;
 declare const TrackedDetectionSchema: z.ZodObject<{
     trackId: z.ZodString;
     className: z.ZodString;
@@ -244,7 +262,9 @@ export declare const ScoredObjectEventSchema: z.ZodObject<{
     frameWidth: z.ZodOptional<z.ZodNumber>;
     frameHeight: z.ZodOptional<z.ZodNumber>;
     mediaKey: z.ZodOptional<z.ZodString>;
+    keyFrameMediaKey: z.ZodOptional<z.ZodString>;
     mediaUrl: z.ZodOptional<z.ZodString>;
+    importance: z.ZodOptional<z.ZodNumber>;
     id: z.ZodString;
     deviceId: z.ZodNumber;
     timestamp: z.ZodNumber;
@@ -305,6 +325,9 @@ export declare const pipelineAnalyticsCapability: {
                 entered: "entered";
             }>;
             active: z.ZodBoolean;
+            importance: z.ZodOptional<z.ZodNumber>;
+            bestEventId: z.ZodOptional<z.ZodString>;
+            importanceReason: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>, import("./capability-definition.js").CapabilityMethodKind>;
         readonly getTrack: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
@@ -352,6 +375,9 @@ export declare const pipelineAnalyticsCapability: {
                 entered: "entered";
             }>;
             active: z.ZodBoolean;
+            importance: z.ZodOptional<z.ZodNumber>;
+            bestEventId: z.ZodOptional<z.ZodString>;
+            importanceReason: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
         /** Historical completed tracks for a device. Queried from the
          *  persisted `pipeline-analytics:tracks` collection; active tracks
@@ -404,6 +430,9 @@ export declare const pipelineAnalyticsCapability: {
                 entered: "entered";
             }>;
             active: z.ZodBoolean;
+            importance: z.ZodOptional<z.ZodNumber>;
+            bestEventId: z.ZodOptional<z.ZodString>;
+            importanceReason: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>, import("./capability-definition.js").CapabilityMethodKind>;
         readonly clearTracks: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
@@ -475,7 +504,9 @@ export declare const pipelineAnalyticsCapability: {
             frameWidth: z.ZodOptional<z.ZodNumber>;
             frameHeight: z.ZodOptional<z.ZodNumber>;
             mediaKey: z.ZodOptional<z.ZodString>;
+            keyFrameMediaKey: z.ZodOptional<z.ZodString>;
             mediaUrl: z.ZodOptional<z.ZodString>;
+            importance: z.ZodOptional<z.ZodNumber>;
             id: z.ZodString;
             deviceId: z.ZodNumber;
             timestamp: z.ZodNumber;
@@ -503,6 +534,31 @@ export declare const pipelineAnalyticsCapability: {
             deviceId: z.ZodNumber;
             timestamp: z.ZodNumber;
         }, z.core.$strip>>>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * Importance-ranked highlights for a device+window. Queries completed
+         * tracks by (deviceId, firstSeen ∈ [since,until]), scores each (or reuses
+         * the persisted score), filters by minImportance/classFilter, orders by
+         * importance desc, and returns up to `limit` compact key events mapped to
+         * each track's best event. Legacy tracks lacking a persisted score are
+         * scored on-read (no write). Degrades to `[]` on error.
+         */
+        readonly getKeyEvents: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            since: z.ZodNumber;
+            until: z.ZodNumber;
+            limit: z.ZodDefault<z.ZodNumber>;
+            minImportance: z.ZodOptional<z.ZodNumber>;
+            classFilter: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            trackId: z.ZodString;
+            timestamp: z.ZodNumber;
+            className: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            importance: z.ZodNumber;
+            bestEventId: z.ZodString;
+            windowMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>, import("./capability-definition.js").CapabilityMethodKind>;
         /** Server-side bucketed event counts for the 24-hour timeline.
          *  Returns one entry per non-empty bucket; empty buckets are omitted. */
         readonly getEventDensity: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
@@ -544,6 +600,7 @@ export declare const pipelineAnalyticsCapability: {
                 fullFrameBoxed: "fullFrameBoxed";
                 faceCrop: "faceCrop";
                 plateCrop: "plateCrop";
+                keyFrame: "keyFrame";
             }>>;
         }, z.core.$strip>, z.ZodReadonly<z.ZodArray<z.ZodObject<{
             key: z.ZodString;
@@ -557,6 +614,7 @@ export declare const pipelineAnalyticsCapability: {
                 fullFrameBoxed: "fullFrameBoxed";
                 faceCrop: "faceCrop";
                 plateCrop: "plateCrop";
+                keyFrame: "keyFrame";
             }>;
             base64: z.ZodString;
             sizeBytes: z.ZodNumber;
@@ -576,6 +634,7 @@ export declare const pipelineAnalyticsCapability: {
                 fullFrameBoxed: "fullFrameBoxed";
                 faceCrop: "faceCrop";
                 plateCrop: "plateCrop";
+                keyFrame: "keyFrame";
             }>;
             base64: z.ZodString;
             sizeBytes: z.ZodNumber;
@@ -625,7 +684,9 @@ export declare const pipelineAnalyticsCapability: {
             frameWidth: z.ZodOptional<z.ZodNumber>;
             frameHeight: z.ZodOptional<z.ZodNumber>;
             mediaKey: z.ZodOptional<z.ZodString>;
+            keyFrameMediaKey: z.ZodOptional<z.ZodString>;
             mediaUrl: z.ZodOptional<z.ZodString>;
+            importance: z.ZodOptional<z.ZodNumber>;
             id: z.ZodString;
             deviceId: z.ZodNumber;
             timestamp: z.ZodNumber;
@@ -699,4 +760,4 @@ export declare const pipelineAnalyticsCapability: {
     };
 };
 export type IPipelineAnalyticsProvider = InferProvider<typeof pipelineAnalyticsCapability>;
-export { TrackStateSchema, EventKindSchema, TrackSchema, MotionEventSchema, ObjectEventSchema, AudioEventSchema, MediaFileKindEnum, MediaFileSchema, TrackedDetectionSchema, };
+export { TrackStateSchema, EventKindSchema, TrackSchema, KeyEventSchema, MotionEventSchema, ObjectEventSchema, AudioEventSchema, MediaFileKindEnum, MediaFileSchema, TrackedDetectionSchema, };

package/dist/capabilities/pipeline-executor.cap.d.ts

@@ -891,6 +891,10 @@ export declare const pipelineExecutorCapability: {
             referenceImage: z.ZodOptional<z.ZodString>;
             deviceId: z.ZodOptional<z.ZodNumber>;
             sessionId: z.ZodOptional<z.ZodString>;
+            plane: z.ZodOptional<z.ZodEnum<{
+                frame: "frame";
+                full: "full";
+            }>>;
         }, z.core.$strip>, z.ZodCustom<FrameResult, FrameResult>, "mutation">;
         /**
          * Batched run — N raw frames packed into one cap call. The provider

package/dist/capabilities/pipeline-runner.cap.d.ts

@@ -1,6 +1,59 @@
 import { z } from 'zod';
 import { type InferProvider } from './capability-definition.js';
 import type { ConfigField } from '../interfaces/config-ui.js';
+/**
+ * A bounding box in NORMALIZED [0,1] frame coordinates for `getNativeCrop`. The
+ * decode worker resolves it against the RETAINED native frame's real pixel dims,
+ * so the caller supplies only the detection-res bbox divided by the detection
+ * dims — no native resolution to plumb.
+ */
+export declare const NativeCropBboxSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    w: z.ZodNumber;
+    h: z.ZodNumber;
+}, z.core.$strip>;
+/** Result of a best-effort native-resolution crop (`getNativeCrop`). */
+export declare const NativeCropResultSchema: z.ZodObject<{
+    bytes: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+export type NativeCropBbox = z.infer<typeof NativeCropBboxSchema>;
+export type NativeCropCapResult = z.infer<typeof NativeCropResultSchema>;
+/** Parent detection context passed to `runDetailSubtree` — the crop's
+ *  originating detection, in FRAME-space coordinates. Reuses
+ *  `NativeCropBboxSchema`'s `{x,y,w,h}` shape (same numeric fields; here
+ *  the coordinates are frame-space rather than getNativeCrop's
+ *  normalized [0,1] convention). */
+declare const DetailParentSchema: z.ZodObject<{
+    bbox: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        w: z.ZodNumber;
+        h: z.ZodNumber;
+    }, z.core.$strip>;
+    className: z.ZodString;
+}, z.core.$strip>;
+/** One child-step result from `runDetailSubtree` — an embedding, label,
+ *  or refined detection produced by running the crop-subtree on a
+ *  single tracked detection. */
+declare const DetailResultSchema: z.ZodObject<{
+    stepId: z.ZodString;
+    className: z.ZodString;
+    score: z.ZodNumber;
+    bbox: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        w: z.ZodNumber;
+        h: z.ZodNumber;
+    }, z.core.$strip>>;
+    embedding: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    alignedCropJpeg: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DetailParent = z.infer<typeof DetailParentSchema>;
+export type DetailResult = z.infer<typeof DetailResultSchema>;
 /**
  * Source enum for motion signals fed to the runner. Extensible — add
  * new variants here when new motion-trigger paths are wired in
@@ -375,7 +428,122 @@ export declare const pipelineRunnerCapability: {
         }, z.core.$strip>>>, import("./capability-definition.js").CapabilityMethodKind>;
         /** List the deviceIds currently attached to this runner. */
         readonly getLocalCameras: import("./capability-definition.js").CapabilityMethodSchema<z.ZodVoid, z.ZodReadonly<z.ZodArray<z.ZodNumber>>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * Best-effort NATIVE-resolution crop of a retention-ring frame. Given the
+         * `FrameHandle` that rode an inference-result event and a normalized `bbox`,
+         * the runner asks the decode worker still holding that frame's NATIVE
+         * surface to GPU/CPU-crop ONLY the ROI at native res and download just the
+         * crop. Returns `null` on a miss (handle not registered, or the worker's
+         * tiny native-retention ring already evicted the frame) — the caller falls
+         * back to a detection-frame crop. Routed to the frame's owning node by
+         * `handle.nodeId`; NEVER ships a full native frame.
+         */
+        readonly getNativeCrop: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            handle: z.ZodObject<{
+                shmId: z.ZodString;
+                slot: z.ZodNumber;
+                seq: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                format: z.ZodEnum<{
+                    jpeg: "jpeg";
+                    rgb: "rgb";
+                    bgr: "bgr";
+                    yuv420: "yuv420";
+                    gray: "gray";
+                }>;
+                pts: z.ZodNumber;
+                byteLength: z.ZodNumber;
+                nodeId: z.ZodString;
+                slotCount: z.ZodNumber;
+            }, z.core.$strip>;
+            bbox: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                w: z.ZodNumber;
+                h: z.ZodNumber;
+            }, z.core.$strip>;
+            maxWidth: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodNullable<z.ZodObject<{
+            bytes: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * Two-plane design: run the DETAIL subtree (crop children —
+         * embedding, classifier, refiner steps whose `inputClasses ≠ null`)
+         * for a single tracked detection. The per-frame plane (`runPipeline`
+         * with `plane: 'frame'`) skips crop children entirely; a track-level
+         * caller invokes this per-track, on its own cadence, instead of on
+         * every frame. Takes either a `frameHandle` (shm lease/session —
+         * preferred, zero-copy) or a `cropJpeg` fallback when the lease/
+         * session backing the frame is already gone. `steps` narrows which
+         * configured children to run (default: all configured children for
+         * `parent.className`). Returns `null` when neither frame source is
+         * resolvable (handle evicted and no cropJpeg fallback supplied).
+         */
+        readonly runDetailSubtree: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            frameHandle: z.ZodOptional<z.ZodObject<{
+                shmId: z.ZodString;
+                slot: z.ZodNumber;
+                seq: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                format: z.ZodEnum<{
+                    jpeg: "jpeg";
+                    rgb: "rgb";
+                    bgr: "bgr";
+                    yuv420: "yuv420";
+                    gray: "gray";
+                }>;
+                pts: z.ZodNumber;
+                byteLength: z.ZodNumber;
+                nodeId: z.ZodString;
+                slotCount: z.ZodNumber;
+            }, z.core.$strip>>;
+            cropJpeg: z.ZodOptional<z.ZodString>;
+            parent: z.ZodObject<{
+                bbox: z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                    w: z.ZodNumber;
+                    h: z.ZodNumber;
+                }, z.core.$strip>;
+                className: z.ZodString;
+            }, z.core.$strip>;
+            steps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>, z.ZodNullable<z.ZodObject<{
+            details: z.ZodArray<z.ZodObject<{
+                stepId: z.ZodString;
+                className: z.ZodString;
+                score: z.ZodNumber;
+                bbox: z.ZodOptional<z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                    w: z.ZodNumber;
+                    h: z.ZodNumber;
+                }, z.core.$strip>>;
+                embedding: z.ZodOptional<z.ZodString>;
+                label: z.ZodOptional<z.ZodString>;
+                alignedCropJpeg: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>, "mutation">;
     };
 };
 export type IPipelineRunnerProvider = InferProvider<typeof pipelineRunnerCapability>;
+/**
+ * Named input/output types for `runDetailSubtree`, derived from the cap
+ * definition above (`InferProvider`) rather than a standalone exported zod
+ * schema — the method's input stays an INLINE `z.object({...})` literal so
+ * `scripts/lib/parse-cap.ts`'s `deviceBound` regex (which only scans a
+ * method's own inline call body for `deviceId: z.number(`) keeps detecting
+ * it as device-bound and `generate-device-proxy.ts` keeps mounting it on
+ * `DeviceProxy.pipelineRunner`. Extracting the input into a separate named
+ * schema constant (as `RunnerCameraConfigSchema` does for `attachCamera`)
+ * would silently drop it from the device proxy — verified via `npm run
+ * codegen` while implementing this cap.
+ */
+export type RunDetailSubtreeInput = Parameters<IPipelineRunnerProvider['runDetailSubtree']>[0];
+export type RunDetailSubtreeResult = NonNullable<Awaited<ReturnType<IPipelineRunnerProvider['runDetailSubtree']>>>;
 export { RunnerCameraConfigSchema, RunnerLocalLoadSchema, RunnerLocalMetricsSchema };