@synnaxlabs/client 0.43.0 → 0.44.1

package/src/hardware/task/client.ts

@@ -8,96 +8,114 @@
 // included in the file licenses/APL.txt.
 
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
-import { id } from "@synnaxlabs/x";
+import { caseconv, id } from "@synnaxlabs/x";
 import { array } from "@synnaxlabs/x/array";
-import { type UnknownRecord } from "@synnaxlabs/x/record";
-import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
 import { type CrudeTimeSpan, TimeSpan } from "@synnaxlabs/x/telem";
-import { z } from "zod/v4";
+import { z } from "zod";
 
-import { framer } from "@/framer";
+import { type framer } from "@/framer";
 import { keyZ as rackKeyZ } from "@/hardware/rack/payload";
 import {
-  type Command,
-  type CommandObservable,
-  commandZ,
   type Key,
   keyZ,
   type New,
   newZ,
-  ONTOLOGY_TYPE,
   type Payload,
-  type State,
-  type StateObservable,
-  stateZ,
+  type Schemas,
+  type Status,
+  statusZ,
   taskZ,
 } from "@/hardware/task/payload";
-import { ontology } from "@/ontology";
+import { type ontology } from "@/ontology";
 import { type ranger } from "@/ranger";
-import { signals } from "@/signals";
-import { analyzeParams, checkForMultipleOrNoResults } from "@/util/retrieve";
+import { checkForMultipleOrNoResults } from "@/util/retrieve";
 import { nullableArrayZ } from "@/util/zod";
 
-const STATE_CHANNEL_NAME = "sy_task_state";
-const COMMAND_CHANNEL_NAME = "sy_task_cmd";
-const SET_CHANNEL_NAME = "sy_task_set";
-const DELETE_CHANNEL_NAME = "sy_task_delete";
+export const STATUS_CHANNEL_NAME = "sy_task_status";
+export const COMMAND_CHANNEL_NAME = "sy_task_cmd";
+export const SET_CHANNEL_NAME = "sy_task_set";
+export const DELETE_CHANNEL_NAME = "sy_task_delete";
 
 const NOT_CREATED_ERROR = new Error("Task not created");
 
 const retrieveSnapshottedTo = async (taskKey: Key, ontologyClient: ontology.Client) => {
-  const task = await ontologyClient.retrieveParents(taskKey);
-  if (task.length === 0) return null;
-  return task[0];
+  const parents = await ontologyClient.retrieveParents(ontologyID(taskKey));
+  if (parents.length === 0) return null;
+  return parents[0];
 };
 
 export class Task<
-  Config extends UnknownRecord = UnknownRecord,
-  Details extends {} = UnknownRecord,
-  Type extends string = string,
+  Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+  Config extends z.ZodType = z.ZodType,
+  StatusData extends z.ZodType = z.ZodType,
 > {
   readonly key: Key;
   name: string;
-  readonly internal: boolean;
-  readonly type: Type;
-  config: Config;
-  readonly snapshot: boolean;
-  state?: State<Details>;
-  private readonly frameClient: framer.Client | null;
-  private readonly ontologyClient: ontology.Client | null;
-  private readonly rangeClient: ranger.Client | null;
+  internal: boolean;
+  type: z.infer<Type>;
+  snapshot: boolean;
+  config: z.infer<Config>;
+  status?: Status<StatusData>;
+
+  readonly schemas: Schemas<Type, Config, StatusData>;
+  private readonly frameClient_?: framer.Client;
+  private readonly ontologyClient_?: ontology.Client;
+  private readonly rangeClient_?: ranger.Client;
+
+  get frameClient(): framer.Client {
+    if (this.frameClient_ == null) throw NOT_CREATED_ERROR;
+    return this.frameClient_;
+  }
+
+  get ontologyClient(): ontology.Client {
+    if (this.ontologyClient_ == null) throw NOT_CREATED_ERROR;
+    return this.ontologyClient_;
+  }
+
+  get rangeClient(): ranger.Client {
+    if (this.rangeClient_ == null) throw NOT_CREATED_ERROR;
+    return this.rangeClient_;
+  }
 
   constructor(
-    key: Key,
-    name: string,
-    type: Type,
-    config: Config,
-    internal: boolean = false,
-    snapshot: boolean = false,
-    state?: State<Details> | null,
-    frameClient: framer.Client | null = null,
-    ontologyClient: ontology.Client | null = null,
-    rangeClient: ranger.Client | null = null,
+    {
+      key,
+      type,
+      name,
+      config,
+      internal = false,
+      snapshot = false,
+      status,
+    }: Payload<Type, Config, StatusData>,
+    schemas?: Schemas<Type, Config, StatusData>,
+    frameClient?: framer.Client,
+    ontologyClient?: ontology.Client,
+    rangeClient?: ranger.Client,
   ) {
     this.key = key;
     this.name = name;
     this.type = type;
     this.config = config;
+    this.schemas = schemas ?? {
+      typeSchema: z.string() as unknown as Type,
+      configSchema: z.unknown() as unknown as Config,
+      statusDataSchema: z.unknown() as unknown as StatusData,
+    };
     this.internal = internal;
     this.snapshot = snapshot;
-    if (state !== null) this.state = state;
-    this.frameClient = frameClient;
-    this.ontologyClient = ontologyClient;
-    this.rangeClient = rangeClient;
+    this.status = status;
+    this.frameClient_ = frameClient;
+    this.ontologyClient_ = ontologyClient;
+    this.rangeClient_ = rangeClient;
   }
 
-  get payload(): Payload<Config, Details, Type> {
+  get payload(): Payload<Type, Config, StatusData> {
     return {
       key: this.key,
       name: this.name,
       type: this.type,
       config: this.config,
-      state: this.state,
+      status: this.status,
       internal: this.internal,
     };
   }
@@ -106,79 +124,23 @@ export class Task<
     return ontologyID(this.key);
   }
 
-  async executeCommand<Args>(type: string, args?: Args): Promise<string> {
-    if (this.frameClient == null) throw NOT_CREATED_ERROR;
-    const writer = await this.frameClient.openWriter(COMMAND_CHANNEL_NAME);
-    const key = id.create();
-    await writer.write(COMMAND_CHANNEL_NAME, [{ task: this.key, type, key, args }]);
-    await writer.close();
-    return key;
+  async executeCommand(type: string, args?: {}): Promise<string> {
+    return await executeCommand(this.frameClient, this.key, type, args);
   }
 
-  async executeCommandSync<Details extends {} = UnknownRecord>(
+  async executeCommandSync(
     type: string,
-    args: UnknownRecord,
     timeout: CrudeTimeSpan,
-  ): Promise<State<Details>> {
-    if (this.frameClient == null) throw NOT_CREATED_ERROR;
-    const streamer = await this.frameClient.openStreamer(STATE_CHANNEL_NAME);
-    const cmdKey = await this.executeCommand(type, args);
-    let res: State<Details>;
-    const to = new Promise((resolve) =>
-      setTimeout(() => resolve(false), new TimeSpan(timeout).milliseconds),
-    );
-    while (true) {
-      const frame = (await Promise.any([streamer.read(), to])) as framer.Frame | false;
-      if (frame === false) throw new Error("Command timed out");
-      const parsed = stateZ.safeParse(frame.at(-1).sy_task_state);
-      if (parsed.success) {
-        res = parsed.data as State<Details>;
-        if (res.key === cmdKey) break;
-      } else throw parsed.error;
-    }
-    streamer.close();
-    return res;
-  }
-
-  async openStateObserver<Details extends {} = UnknownRecord>(): Promise<
-    StateObservable<Details>
-  > {
-    if (this.frameClient == null) throw NOT_CREATED_ERROR;
-    return new framer.ObservableStreamer<State<Details>>(
-      await this.frameClient.openStreamer(STATE_CHANNEL_NAME),
-      (frame) => {
-        const s = frame.get(STATE_CHANNEL_NAME);
-        if (s.length === 0) return [null, false];
-        const parse = stateZ.safeParse(s.at(-1));
-        if (!parse.success) {
-          console.error(parse.error);
-          return [null, false];
-        }
-        const state = parse.data;
-        if (state.task !== this.key) return [null, false];
-        return [state as State<Details>, true];
-      },
-    );
-  }
-
-  async openCommandObserver<Args extends {} = UnknownRecord>(): Promise<
-    CommandObservable<Args>
-  > {
-    if (this.frameClient == null) throw NOT_CREATED_ERROR;
-    return new framer.ObservableStreamer<Command<Args>>(
-      await this.frameClient.openStreamer(COMMAND_CHANNEL_NAME),
-      (frame) => {
-        const s = frame.get(COMMAND_CHANNEL_NAME);
-        if (s.length === 0) return [null, false];
-        const parse = commandZ.safeParse(s.at(-1));
-        if (!parse.success) {
-          console.error(parse.error);
-          return [null, false];
-        }
-        const cmd = parse.data;
-        if (cmd.task !== this.key) return [null, false];
-        return [cmd as Command<Args>, true];
-      },
+    args?: {},
+  ): Promise<Status<StatusData>> {
+    return await executeCommandSync<StatusData>(
+      this.frameClient,
+      this.key,
+      type,
+      timeout,
+      this.name,
+      this.schemas?.statusDataSchema,
+      args,
     );
   }
 
@@ -195,35 +157,80 @@ const retrieveReqZ = z.object({
   keys: keyZ.array().optional(),
   names: z.string().array().optional(),
   types: z.string().array().optional(),
-  includeState: z.boolean().optional(),
+  includeStatus: z.boolean().optional(),
   offset: z.number().optional(),
   limit: z.number().optional(),
 });
 
-const retrieveResZ = z.object({ tasks: nullableArrayZ(taskZ) });
+const singleRetrieveArgsZ = z.union([
+  z
+    .object({ key: keyZ, includeStatus: z.boolean().optional() })
+    .transform(({ key, includeStatus }) => ({ keys: [key], includeStatus })),
+  z
+    .object({ name: z.string(), includeStatus: z.boolean().optional() })
+    .transform(({ name, includeStatus }) => ({ names: [name], includeStatus })),
+]);
+export type SingleRetrieveArgs = z.input<typeof singleRetrieveArgsZ>;
+
+const multiRetrieveArgsZ = retrieveReqZ;
+export type MultiRetrieveArgs = z.input<typeof multiRetrieveArgsZ>;
+
+const retrieveArgsZ = z.union([singleRetrieveArgsZ, multiRetrieveArgsZ]);
+export type RetrieveArgs = z.input<typeof retrieveArgsZ>;
+
+type RetrieveSchemas<
+  Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+  Config extends z.ZodType = z.ZodType,
+  StatusData extends z.ZodType = z.ZodType,
+> = {
+  schemas?: Schemas<Type, Config, StatusData>;
+};
 
-export interface RetrieveRequest extends z.infer<typeof retrieveReqZ> {}
+const retrieveResZ = <
+  Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+  Config extends z.ZodType = z.ZodType,
+  StatusData extends z.ZodType = z.ZodType,
+>(
+  schemas?: Schemas<Type, Config, StatusData>,
+) =>
+  z.object({
+    tasks: nullableArrayZ(taskZ(schemas)),
+  });
 
-export interface RetrieveOptions
-  extends Pick<
-    RetrieveRequest,
-    "rack" | "offset" | "limit" | "includeState" | "types"
-  > {}
+export interface RetrieveRequest extends z.infer<typeof retrieveReqZ> {}
 
 const RETRIEVE_ENDPOINT = "/hardware/task/retrieve";
 const CREATE_ENDPOINT = "/hardware/task/create";
 const DELETE_ENDPOINT = "/hardware/task/delete";
 const COPY_ENDPOINT = "/hardware/task/copy";
 
-const createReqZ = z.object({ tasks: newZ.array() });
-const createResZ = z.object({ tasks: taskZ.array() });
+const createReqZ = <
+  Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+  Config extends z.ZodType = z.ZodType,
+  StatusData extends z.ZodType = z.ZodType,
+>(
+  schemas?: Schemas<Type, Config, StatusData>,
+) => z.object({ tasks: newZ(schemas).array() });
+const createResZ = <
+  Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+  Config extends z.ZodType = z.ZodType,
+  StatusData extends z.ZodType = z.ZodType,
+>(
+  schemas?: Schemas<Type, Config, StatusData>,
+) => z.object({ tasks: taskZ(schemas).array() });
 const deleteReqZ = z.object({ keys: keyZ.array() });
 const deleteResZ = z.object({});
 const copyReqZ = z.object({ key: keyZ, name: z.string(), snapshot: z.boolean() });
-const copyResZ = z.object({ task: taskZ });
-
-export class Client implements AsyncTermSearcher<string, Key, Payload> {
-  readonly type: string = ONTOLOGY_TYPE;
+const copyResZ = <
+  Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+  Config extends z.ZodType = z.ZodType,
+  StatusData extends z.ZodType = z.ZodType,
+>(
+  schemas?: Schemas<Type, Config, StatusData>,
+) => z.object({ task: taskZ(schemas) });
+
+export class Client {
+  readonly type: string = "task";
   private readonly client: UnaryClient;
   private readonly frameClient: framer.Client;
   private readonly ontologyClient: ontology.Client;
@@ -241,38 +248,53 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
     this.rangeClient = rangeClient;
   }
 
-  async create<
-    Config extends UnknownRecord = UnknownRecord,
-    Details extends {} = UnknownRecord,
-    Type extends string = string,
-  >(task: New<Config, Type>): Promise<Task<Config, Details, Type>>;
+  async create(task: New): Promise<Task>;
+  async create(tasks: New[]): Promise<Task[]>;
+  async create(task: New | New[]): Promise<Task | Task[]>;
 
   async create<
-    Config extends UnknownRecord = UnknownRecord,
-    Details extends {} = UnknownRecord,
-    Type extends string = string,
-  >(tasks: New<Config, Type>[]): Promise<Task<Config, Details, Type>[]>;
+    Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+    Config extends z.ZodType = z.ZodType,
+    StatusData extends z.ZodType = z.ZodType,
+  >(
+    task: New<Type, Config>,
+    schemas: Schemas<Type, Config, StatusData>,
+  ): Promise<Task<Type, Config, StatusData>>;
+  async create<
+    Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+    Config extends z.ZodType = z.ZodType,
+    StatusData extends z.ZodType = z.ZodType,
+  >(
+    tasks: New<Type, Config>[],
+    schemas: Schemas<Type, Config, StatusData>,
+  ): Promise<Task<Type, Config, StatusData>[]>;
 
   async create<
-    Config extends UnknownRecord = UnknownRecord,
-    Details extends {} = UnknownRecord,
-    Type extends string = string,
+    Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+    Config extends z.ZodType = z.ZodType,
+    StatusData extends z.ZodType = z.ZodType,
   >(
-    task: New<Config, Type> | Array<New<Config, Type>>,
-  ): Promise<Task<Config, Details, Type> | Array<Task<Config, Details, Type>>> {
+    task: New<Type, Config> | Array<New<Type, Config>>,
+    schemas?: Schemas<Type, Config, StatusData>,
+  ): Promise<Task<Type, Config, StatusData> | Array<Task<Type, Config, StatusData>>> {
     const isSingle = !Array.isArray(task);
-    const res = await sendRequired<typeof createReqZ, typeof createResZ>(
+    const createReq = createReqZ(schemas);
+    const createRes = createResZ(schemas);
+    const res = await sendRequired(
       this.client,
       CREATE_ENDPOINT,
-      { tasks: array.toArray(task) },
-      createReqZ,
-      createResZ,
+      { tasks: array.toArray(task) } as z.infer<typeof createReq>,
+      createReq,
+      createRes,
+    );
+    const sugared = this.sugar<Type, Config, StatusData>(
+      res.tasks as Payload<Type, Config, StatusData>[],
+      schemas,
     );
-    const sugared = this.sugar(res.tasks) as Array<Task<Config, Details, Type>>;
     return isSingle ? sugared[0] : sugared;
   }
 
-  async delete(keys: bigint | bigint[]): Promise<void> {
+  async delete(keys: Key | Key[]): Promise<void> {
     await sendRequired<typeof deleteReqZ, typeof deleteResZ>(
       this.client,
       DELETE_ENDPOINT,
@@ -282,85 +304,56 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
     );
   }
 
-  async search(term: string): Promise<Payload[]> {
-    return await this.execRetrieve({ keys: [term] });
-  }
-
-  async page(offset: number, limit: number): Promise<Payload[]> {
-    return await this.execRetrieve({ offset, limit });
-  }
-
-  async list(options: RetrieveOptions = {}): Promise<Task[]> {
-    return this.sugar(await this.execRetrieve(options));
-  }
-
-  async retrieve<
-    Config extends UnknownRecord = UnknownRecord,
-    Details extends {} = UnknownRecord,
-    Type extends string = string,
-  >(rack: number, options?: RetrieveOptions): Promise<Task<Config, Details, Type>[]>;
-
-  async retrieve<
-    Config extends UnknownRecord = UnknownRecord,
-    Details extends {} = UnknownRecord,
-    Type extends string = string,
-  >(keys: string[], options?: RetrieveOptions): Promise<Task<Config, Details, Type>[]>;
-
   async retrieve<
-    Config extends UnknownRecord = UnknownRecord,
-    Details extends {} = UnknownRecord,
-    Type extends string = string,
-  >(key: string, options?: RetrieveOptions): Promise<Task<Config, Details, Type>>;
-
+    Type extends z.ZodLiteral<string>,
+    Config extends z.ZodType,
+    StatusData extends z.ZodType,
+  >(
+    args: SingleRetrieveArgs & RetrieveSchemas<Type, Config, StatusData>,
+  ): Promise<Task<Type, Config, StatusData>>;
+  async retrieve(args: SingleRetrieveArgs): Promise<Task>;
   async retrieve<
-    Config extends UnknownRecord = UnknownRecord,
-    Details extends {} = UnknownRecord,
-    Type extends string = string,
+    Type extends z.ZodLiteral<string>,
+    Config extends z.ZodType,
+    StatusData extends z.ZodType,
   >(
-    rack: number | string | string[],
-    options?: RetrieveOptions,
-  ): Promise<Task<Config, Details, Type> | Task<Config, Details, Type>[]> {
-    const { single, normalized, variant } = analyzeParams(
-      rack,
-      { number: "rack", string: "keys" },
-      { convertNumericStrings: false },
+    args: MultiRetrieveArgs & RetrieveSchemas<Type, Config, StatusData>,
+  ): Promise<Task<Type, Config, StatusData>[]>;
+  async retrieve(args: MultiRetrieveArgs): Promise<Task[]>;
+  async retrieve<
+    Type extends z.ZodLiteral<string>,
+    Config extends z.ZodType,
+    StatusData extends z.ZodType,
+  >({
+    schemas,
+    ...args
+  }: RetrieveArgs & RetrieveSchemas<Type, Config, StatusData>): Promise<
+    Task<Type, Config, StatusData> | Task<Type, Config, StatusData>[]
+  > {
+    const isSingle = "key" in args || "name" in args;
+    const res = await sendRequired(
+      this.client,
+      RETRIEVE_ENDPOINT,
+      args,
+      retrieveArgsZ,
+      retrieveResZ(schemas),
     );
-    const req: RetrieveRequest = { ...options };
-    if (variant === "rack") req.rack = rack as number;
-    else req.keys = normalized as string[];
-    const tasks = await this.execRetrieve(req);
-    const sugared = this.sugar(tasks) as Array<Task<Config, Details, Type>>;
-    return single && variant !== "rack" ? sugared[0] : sugared;
+    const tasks = res.tasks as Payload<Type, Config, StatusData>[];
+    const sugared = this.sugar<Type, Config, StatusData>(tasks, schemas);
+    checkForMultipleOrNoResults("Task", args, sugared, isSingle);
+    return isSingle ? sugared[0] : sugared;
   }
 
   async copy(key: string, name: string, snapshot: boolean): Promise<Task> {
-    const res = await sendRequired(
+    const copyRes = copyResZ();
+    const response = await sendRequired(
       this.client,
       COPY_ENDPOINT,
       { key, name, snapshot },
       copyReqZ,
-      copyResZ,
+      copyRes,
     );
-    return this.sugar([res.task])[0];
-  }
-
-  async retrieveByName<
-    Config extends UnknownRecord = UnknownRecord,
-    Details extends {} = UnknownRecord,
-    Type extends string = string,
-  >(name: string, rack?: number): Promise<Task<Config, Details, Type>> {
-    const tasks = await this.execRetrieve({ names: [name], rack });
-    checkForMultipleOrNoResults("Task", name, tasks, true);
-    return this.sugar(tasks)[0] as Task<Config, Details, Type>;
-  }
-
-  async retrieveByType<
-    Config extends UnknownRecord = UnknownRecord,
-    Details extends {} = UnknownRecord,
-    Type extends string = string,
-  >(type: Type, rack?: number): Promise<Task<Config, Details, Type>[]> {
-    const tasks = await this.execRetrieve({ types: [type], rack });
-    return this.sugar(tasks) as Task<Config, Details, Type>[];
+    return this.sugar(response.task as Payload);
   }
 
   async retrieveSnapshottedTo(taskKey: Key): Promise<ontology.Resource | null> {
@@ -368,97 +361,148 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
     return await retrieveSnapshottedTo(taskKey, this.ontologyClient);
   }
 
-  private async execRetrieve(req: RetrieveRequest): Promise<Payload[]> {
-    const res = await sendRequired(
-      this.client,
-      RETRIEVE_ENDPOINT,
-      req,
-      retrieveReqZ,
-      retrieveResZ,
-    );
-    return res.tasks;
-  }
-
   sugar<
-    Config extends UnknownRecord = UnknownRecord,
-    Details extends {} = UnknownRecord,
-    Type extends string = string,
-  >(payload: Payload<Config, Details, Type>): Task<Config, Details, Type>;
+    Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+    Config extends z.ZodType = z.ZodType,
+    StatusData extends z.ZodType = z.ZodType,
+  >(
+    payloads: Payload<Type, Config, StatusData>[],
+    schemas?: Schemas<Type, Config, StatusData>,
+  ): Task<Type, Config, StatusData>[];
 
   sugar<
-    Config extends UnknownRecord = UnknownRecord,
-    Details extends {} = UnknownRecord,
-    Type extends string = string,
-  >(payloads: Payload<Config, Details, Type>[]): Task<Config, Details, Type>[];
+    Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+    Config extends z.ZodType = z.ZodType,
+    StatusData extends z.ZodType = z.ZodType,
+  >(
+    payload: Payload<Type, Config, StatusData>,
+    schemas?: Schemas<Type, Config, StatusData>,
+  ): Task<Type, Config, StatusData>;
 
-  sugar(payloads: Payload | Payload[]): Task | Task[] {
+  sugar<
+    Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
+    Config extends z.ZodType = z.ZodType,
+    StatusData extends z.ZodType = z.ZodType,
+  >(
+    payloads: Payload<Type, Config, StatusData> | Payload<Type, Config, StatusData>[],
+    schemas?: Schemas<Type, Config, StatusData>,
+  ): Task<Type, Config, StatusData>[] | Task<Type, Config, StatusData> {
     const isSingle = !Array.isArray(payloads);
-    const res = array
-      .toArray(payloads)
-      .map(
-        ({ key, name, type, config, state, internal, snapshot }) =>
-          new Task(
+    const res = array.toArray(payloads).map(
+      ({ key, name, type, config, status, internal, snapshot }) =>
+        new Task(
+          {
             key,
             name,
             type,
             config,
             internal,
             snapshot,
-            state,
-            this.frameClient,
-            this.ontologyClient,
-            this.rangeClient,
-          ),
-      );
+            status,
+          },
+          schemas,
+          this.frameClient,
+          this.ontologyClient,
+          this.rangeClient,
+        ),
+    );
     return isSingle ? res[0] : res;
   }
 
-  async openTracker(): Promise<signals.Observable<string, string>> {
-    return await signals.openObservable<string, string>(
+  async executeCommand(task: Key, type: string, args?: {}): Promise<string> {
+    return await executeCommand(this.frameClient, task, type, args);
+  }
+
+  async executeCommandSync<StatusData extends z.ZodType = z.ZodType>(
+    task: Key,
+    type: string,
+    timeout: CrudeTimeSpan,
+    args?: {},
+    name?: string,
+    statusDataZ: StatusData = z.unknown() as unknown as StatusData,
+  ): Promise<Status<StatusData>> {
+    const retrieveName = async () => {
+      const t = await this.retrieve({ key: task });
+      return t.name;
+    };
+    return await executeCommandSync(
       this.frameClient,
-      SET_CHANNEL_NAME,
-      DELETE_CHANNEL_NAME,
-      (variant, data) =>
-        Array.from(data).map((k) => ({
-          variant,
-          key: k.toString(),
-          value: k.toString(),
-        })),
+      task,
+      type,
+      timeout,
+      name ?? retrieveName,
+      statusDataZ,
+      args,
     );
   }
+}
 
-  async openStateObserver(): Promise<StateObservable> {
-    return new framer.ObservableStreamer<State>(
-      await this.frameClient.openStreamer(STATE_CHANNEL_NAME),
-      (frame) => {
-        const s = frame.get(STATE_CHANNEL_NAME);
-        if (s.length === 0) return [null, false];
-        const parse = stateZ.safeParse(s.at(-1));
-        if (!parse.success) {
-          console.error(parse.error);
-          return [null, false];
-        }
-        return [parse.data, true];
-      },
-    );
+export const ontologyID = (key: Key): ontology.ID => ({ type: "task", key });
+
+const executeCommand = async (
+  frameClient: framer.Client | null,
+  task: Key,
+  type: string,
+  args?: {},
+): Promise<string> => {
+  if (frameClient == null) throw NOT_CREATED_ERROR;
+  const key = id.create();
+  const w = await frameClient.openWriter(COMMAND_CHANNEL_NAME);
+  await w.write(COMMAND_CHANNEL_NAME, [{ args, key, task, type }]);
+  await w.close();
+  return key;
+};
+
+const executeCommandSync = async <StatusData extends z.ZodType = z.ZodType>(
+  frameClient: framer.Client | null,
+  task: Key,
+  type: string,
+  timeout: CrudeTimeSpan,
+  tskName: string | (() => Promise<string>),
+  statusDataZ: StatusData,
+  args?: {},
+): Promise<Status<StatusData>> => {
+  if (frameClient == null) throw NOT_CREATED_ERROR;
+  const streamer = await frameClient.openStreamer(STATUS_CHANNEL_NAME);
+  const cmdKey = await executeCommand(frameClient, task, type, args);
+  const parsedTimeout = new TimeSpan(timeout);
+
+  let timeoutID: NodeJS.Timeout | undefined;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutID = setTimeout(() => {
+      void (async () =>
+        reject(await formatTimeoutError(type, tskName, parsedTimeout, task)))();
+    }, parsedTimeout.milliseconds);
+  });
+  try {
+    while (true) {
+      const frame = await Promise.race([streamer.read(), timeoutPromise]);
+      const state = statusZ(statusDataZ).parse(frame.at(-1)[STATUS_CHANNEL_NAME]);
+      if (state.key === cmdKey) return state;
+    }
+  } finally {
+    clearTimeout(timeoutID);
+    streamer.close();
   }
+};
 
-  async openCommandObserver(): Promise<CommandObservable> {
-    return new framer.ObservableStreamer<Command>(
-      await this.frameClient.openStreamer(COMMAND_CHANNEL_NAME),
-      (frame) => {
-        const s = frame.get(COMMAND_CHANNEL_NAME);
-        if (s.length === 0) return [null, false];
-        const parse = commandZ.safeParse(s.at(-1));
-        if (!parse.success) {
-          console.error(parse.error);
-          return [null, false];
-        }
-        return [parse.data, true];
-      },
+const formatTimeoutError = async (
+  type: string,
+  name: string | (() => Promise<string>),
+  timeout: TimeSpan,
+  key: Key,
+): Promise<Error> => {
+  const formattedType = caseconv.capitalize(type);
+  const formattedTimeout = timeout.toString();
+  try {
+    const name_ = typeof name === "string" ? name : await name();
+    return new Error(
+      `${formattedType} command to ${name_} timed out after ${formattedTimeout}`,
+    );
+  } catch (e) {
+    console.error("Failed to retrieve task name for timeout error:", e);
+    return new Error(
+      `${formattedType} command to task with key ${key} timed out after ${formattedTimeout}`,
     );
   }
-}
-
-export const ontologyID = (key: Key): ontology.ID =>
-  new ontology.ID({ type: ONTOLOGY_TYPE, key });
+};