@synapse-sdk/client 0.3.0 → 0.3.3

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-import type { Card, ClientType, Delivery, FecParams, MediaFrame, Role, ServiceRef, StoreMode, StoreOnDeath, StoreRow, TimeDomain, TopicRef, TrackDesc, Tlv, JsonSchema } from "@synapse-sdk/core";
-import type { SynapseError } from "@synapse-sdk/core";
+import type { Card, ClientType, Delivery, FecParams, Role, ServiceRef, StoreMode, StoreOnDeath, StoreRow, TimeDomain, TopicRef, TrackDesc, Tlv, JsonSchema } from "@synapse-sdk/core";
+import type { SynapseError, TasksRun } from "@synapse-sdk/core";
 export type { Card, ClientType, Delivery, FecParams, Role, ServiceRef, StoreMode, StoreOnDeath, StoreRow, TimeDomain, TopicRef, TrackDesc };
 /** What the reconnect policy is asked before every attempt. */
 export interface RetryContext {
@@ -13,8 +13,15 @@ export interface ReconnectPolicy {
 }
 export type Transport = "auto" | "webtransport" | "websocket";
 export interface ConnectOptions {
-    /** `https://host:port/<root>`. */
-    url: string;
+    /**
+     * The runtime, `https://host:4470` (the path to dial is learned from the runtime at every attempt). Through a relay: the relay with
+     * the runtime's path, `https://relay:4443/runtimes/<runtime_id>`, and `token`. A `jwt=` in the URL is taken as the token.
+     * Absent: `SYNAPSE_ENDPOINT` (Bun/Node; the runtime sets it for every task it starts); a browser has no environment,
+     * so there it is `invalid_input`.
+     */
+    url?: string;
+    /** The relay token that lets this node through a relay; none for a runtime dialed directly. Never printed. */
+    token?: string;
     /** This node's type (WP §3.1): bounds the role it may exercise; the runtime grants the role. */
     type: ClientType;
     /** This node's name `[a-z0-9_-]{1,64}`; minted (`<type>-<6 hex>`) when absent and kept across reconnects. */
@@ -27,7 +34,7 @@ export interface ConnectOptions {
     brokerCertSha256?: string;
     /** Time-domain id override (WP §7.3); default per runtime. */
     domId?: string;
-    /** Standing project intent (`&project=`, WP §3.5). */
+    /** Standing project intent (WP §3.5), sent with the connect request. */
     project?: "operator";
     /** `null` = no reconnect: a dropped session ends the node `closed`. Default: 100 ms → 10 s, ×2, jitter, unlimited. */
     reconnect?: ReconnectPolicy | null;
@@ -46,6 +53,8 @@ export interface ConnectTarget {
     userId?: string;
     credential?: string;
     brokerCertSha256?: string;
+    /** The relay token for *this* target; left out = no token (a token for another runtime would be refused). */
+    token?: string;
 }
 export type ConnectionState = {
     status: "connecting";
@@ -79,7 +88,9 @@ export interface Info {
     dom: TimeDomain;
     brokerDom: string;
     brokerVersion: string; /** The robot the runtime serves (fixed for the runtime's life; empty between sessions). */
-    robot: string;
+    robot: string; /** The runtime's name in its cluster, from the current session's hello (empty between sessions). */
+    runtimeName: string; /** The runtime's id, from the current session's hello (empty between sessions): kept across the runtime's restarts. */
+    runtimeId: string;
     url: string;
 }
 /** A `promoted`/`demoted` notice on the session (WP §3.5). */
@@ -93,7 +104,7 @@ export type Notice = {
     project: string | null;
 };
 export interface PublishOptions {
-    /** The frame's `t_us` (this node's clock); default now. */
+    /** The frame's `t_us` (this node's clock): the capture time, if you have one; default now. */
     tUs?: number;
     flags?: number;
 }
@@ -121,12 +132,13 @@ export interface Publisher<TIn> extends AsyncDisposable {
     readonly verdict: Verdict;
     /** Resolves once admitted and announced on the current session; `not_connected` once the node ended. A refusal is asked again, paced and warned about. */
     ready(): Promise<void>;
-    /** Synchronous: writes to the installed track, or drops and counts while unbound (SDK §12.4). */
+    /**
+     * Synchronous: writes to the installed track, or drops and counts while unbound (SDK §12.4). A
+     * msgpack topic takes a value; a raw topic takes bytes, sent as given; on a `video/*` topic the
+     * bytes are one access unit (Annex-B for `video/h264`), sent as a `MEDIA` frame whose
+     * `KEY`/`CONFIG`/`RECOVERY` flags are read off the bitstream.
+     */
     publish(value: TIn, opts?: PublishOptions): void;
-    /** Raw topics: any frame type, flags and TLVs (WP §4.1); `MEDIA` frames via `publishMedia`. */
-    publishFrame(type: number, flags: number, tUs: number, tlvs: Tlv[], body: Uint8Array): void;
-    /** Raw topics: a media access unit (`MEDIA`, flags from the frame, `t_us` = capture time, `STAGES` when stamped; a `sentUs` of 0 is stamped at the write). */
-    publishMedia(frame: MediaFrame): void;
     stats(): PublisherStats;
     close(): void;
 }
@@ -141,6 +153,12 @@ export interface Envelope<T> {
     flags: number;
     type: number;
     tlvs: Tlv[];
+    /** Flag `KEY`: an IDR, a decoder may start here (video). */
+    key: boolean;
+    /** Flag `CONFIG`: the access unit carries SPS/PPS (video). */
+    config: boolean;
+    /** Flag `RECOVERY`: a recovery point, a gradual start point (video). */
+    recovery: boolean;
 }
 export interface SubscribeOptions {
     /** Deliver at most one message per interval, newest wins (skipped counted `coalesced`). */
@@ -417,6 +435,9 @@ export interface SceneEntity {
     /** Presentation/status the live plane sets per entity. */
     state?: Record<string, unknown>;
     hardpoints?: Hardpoint[];
+    /** The entity's tasks (`instance` → declaration): what the runtime runs for it while the project's tasks run. */
+    tasks?: Record<string, TaskDeclaration>;
+    /** Passed through untouched; the runtime does not read it (`tasks` supersedes it). */
     behaviors?: Record<string, unknown>;
     possession?: Record<string, unknown>;
     labels?: string[];
@@ -653,6 +674,126 @@ export interface SceneHandle extends AsyncDisposable {
     /** Ends this handle: its verbs fail `not_connected`, its views and feeds end; the node's other scene handles go on. */
     close(): void;
 }
+/**
+ * A declaration: what the runtime runs under an instance name (the robot's: a key of
+ * `tasks.declarations`; a project's: an entry of an entity's `tasks`). Whether it has a process to
+ * run is the catalog's: a task whose spec has nothing to run is passive (counted, never started).
+ */
+export interface TaskDeclaration {
+    /** The task's address, as the task tool lists it (`<workspace>:<pkg>:<task>`); never split. */
+    ref: string;
+    /** `false`: left out of the next run. */
+    enabled?: boolean;
+    /** Passed to the task: as flags, positionals or environment variables per its spec, and whole as `SYNAPSE_CONFIG` (JSON). */
+    config?: Record<string, unknown>;
+    /** The catalog's `schemaHash` this declaration was written against; another one fails the run. */
+    schema?: string;
+}
+/** How a task's last process ended: its exit code, the signal that ended it, or neither. Times are Unix ms. */
+export type TaskExit = {
+    code: number;
+    at: number;
+} | {
+    signal: number;
+    at: number;
+} | {
+    at: number;
+};
+/** One running task, as the runtime shows it. */
+export interface TaskStatus {
+    scope: "robot" | "project";
+    /** The task's address (its declaration's `ref`). */
+    addr: string;
+    instance: string;
+    /** Project tasks: the entity's id. */
+    entity?: string;
+    /** `down`: its process exited and its restart is pending. */
+    state: "up" | "down";
+    /** Unix ms of the last change between `up` and `down`. */
+    since: number;
+    /** How many times its process was started again after an exit. */
+    restarts: number;
+    /** How its last process ended. */
+    exit?: TaskExit;
+    /** The file its stdout and stderr go to. */
+    log: string;
+}
+/** A scope's run and its tasks. */
+export interface TasksRunStatus<T> {
+    /** `undefined`: the runtime has not said yet (not synced, or between sessions). */
+    state: "starting" | "running" | "stopping" | "stopped" | undefined;
+    /** Unix ms of the last change of `state`. */
+    since?: number;
+    /** Why it stopped or failed: `project_switch`, or an error code (`preflight_failed`, `launch_failed`, ...). */
+    reason?: string;
+    tasks: T;
+}
+/** What runs, both scopes: the robot's tasks by instance, the project's by entity id, then instance. */
+export interface TasksStatus {
+    robot: TasksRunStatus<Readonly<Record<string, TaskStatus>>>;
+    project: TasksRunStatus<Readonly<Record<string, Readonly<Record<string, TaskStatus>>>>>;
+}
+/** One task the runtime knows (from the task tool's workspaces). Fields the task's manifest lacks are absent. */
+export interface TaskCatalogEntry {
+    addr: string;
+    workspace: string;
+    pkg?: string;
+    name?: string;
+    kind?: string;
+    tags?: string[];
+    inputs?: JsonSchema;
+    schemaHash?: string;
+    definedBy?: string;
+}
+/** A value the runtime keeps current that this node only reads: it has no writes. */
+export interface ReadonlyStoreHandle<V> {
+    /** The value now; the same object while nothing changed, and an unchanged part keeps its object when another part changes. */
+    readonly value: V;
+    /** `true` while the value is current. */
+    readonly synced: boolean;
+    /** Resolves once the value is current (the first time). */
+    ready(): Promise<void>;
+    /** The whole value after each change. It is state, not history: a reader slower than the changes sees the latest value. */
+    watch(): AsyncIterable<V>;
+    /** The framework bridge (React): called on every change of the value or of `synced`. */
+    subscribe(listener: () => void): () => void;
+}
+/** The robot's task declarations, `instance` → declaration (operators write them). The node owns this handle: it has no `close` or `destroy`. */
+export interface TaskDeclarations extends Omit<StoreHandle, "name" | "value" | "get" | "set" | "watch" | "destroy" | "close" | typeof Symbol.asyncDispose> {
+    readonly value: Readonly<Record<string, TaskDeclaration>>;
+    get(instance: string): TaskDeclaration | undefined;
+    /** `set(instance, declaration)`, or `set({ ... })` for several as one atomic write; waits for the value to be current first, resolves once `value` shows the write. */
+    set(instance: string, declaration: TaskDeclaration): Promise<void>;
+    set(declarations: Record<string, TaskDeclaration>): Promise<void>;
+    /** The whole value after each change; with `instance`, that declaration each time it changes (`undefined` after a delete). */
+    watch(instance?: string): AsyncIterable<unknown>;
+    /** Resolves once the value is current (the first time). */
+    ready(): Promise<void>;
+}
+/**
+ * `node.tasks`: the robot's task declarations, what runs (`status`), what the runtime can run
+ * (`catalog`), and the verbs. Running and stopping need the operator role. A run's reply is the
+ * runtime's answer; what runs afterwards is `status`.
+ */
+export interface Tasks {
+    readonly declarations: TaskDeclarations;
+    readonly status: ReadonlyStoreHandle<TasksStatus>;
+    /** By address. */
+    readonly catalog: ReadonlyStoreHandle<Readonly<Record<string, TaskCatalogEntry>>>;
+    /**
+     * Starts the robot's tasks (the enabled declarations). Every declaration is checked first and nothing starts unless all
+     * pass: a failed check rejects `preflight_failed`, a process that could not start `launch_failed` (what had started is
+     * stopped); both carry the report ({@link isTasksRefusal}). `already_running` while they run. Robot tasks keep running
+     * across project switches.
+     */
+    runRobotTasks(): Promise<TasksRun>;
+    /** Stops every robot task (also when none ran). Project tasks are not touched. */
+    stopRobotTasks(): Promise<void>;
+    /** Starts the active project's tasks (the enabled `tasks` of its scene's entities), as {@link runRobotTasks}; `project_inactive` with no active project. A project switch stops them. */
+    runProjectTasks(): Promise<TasksRun>;
+    /** Stops every project task (also when none ran). Robot tasks are not touched. */
+    stopProjectTasks(): Promise<void>;
+}
 export interface Catalog {
     readonly topics: Readonly<Record<string, {
         desc?: TrackDesc;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapse-sdk/client",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "Synapse SDK client: connect a node to the runtime; topics, services, calls, store, video.",
   "type": "module",
   "sideEffects": false,
@@ -14,7 +14,7 @@
     "dist"
   ],
   "dependencies": {
-    "@synapse-sdk/core": "0.3.0",
+    "@synapse-sdk/core": "0.3.3",
     "@moq/net": "0.4.2"
   },
   "peerDependencies": {