@dxos/compute 0.13.0 → 0.14.0

package/src/Process.ts

@@ -4,15 +4,16 @@
 
 // @import-as-namespace
 
+import * as Cause from 'effect/Cause';
 import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
-import type * as Exit from 'effect/Exit';
+import * as Exit from 'effect/Exit';
 import * as Option from 'effect/Option';
 import type * as Atom from 'effect/reactivity/Atom';
 import type * as Rpc from 'effect/rpc/Rpc';
 import type * as RpcClient from 'effect/rpc/RpcClient';
 import * as Schema from 'effect/Schema';
-import type * as Stream from 'effect/Stream';
+import * as Stream from 'effect/Stream';
 
 import { Annotation, type Database } from '@dxos/echo';
 import { type SpaceId, URI } from '@dxos/keys';
@@ -162,7 +163,7 @@ export interface Filter {
  * Whether `info` satisfies `filter`. Exported so every {@link Manager} filters identically rather
  * than each implementation growing its own notion of a match.
  */
-export const matchesFilter = (info: Process, filter: Filter = {}): boolean => {
+export const matchesFilter = (info: Data, filter: Filter = {}): boolean => {
   if (filter.key !== undefined && info.key !== filter.key) {
     return false;
   }
@@ -190,10 +191,20 @@ export const listFromTree =
   (filter?: Filter): Effect.Effect<readonly Process[]> =>
     Effect.map(processTree, (tree) => tree.filter((info) => matchesFilter(info, filter)));
 
+export interface SubscribeEphemeralOptions {
+  /**
+   * Replay the buffered events before streaming new ones (the default), so a reader attaching mid-turn
+   * sees the turn so far. A reader that subscribes BEFORE causing the work it wants to follow passes
+   * `false`: the buffer then holds only earlier turns, which would read as the new one.
+   */
+  readonly replay?: boolean;
+}
+
 /**
- * A process: one running (or finished) instance of a durable operation, wherever its runtime runs.
+ * The plain fields of a {@link Process}: what a process tree holds, what crosses the wire, and what
+ * {@link make} turns back into a process.
  */
-export interface Process {
+export interface Data {
   readonly pid: ID;
   readonly parentPid: ID | null;
 
@@ -253,10 +264,6 @@ export interface Process {
   };
 }
 
-//
-// Handles.
-//
-
 export interface Status {
   readonly state: State;
   readonly exit: Option.Option<Exit.Exit<void>>;
@@ -265,25 +272,14 @@ export interface Status {
   readonly completedAt: Option.Option<Date>;
 }
 
-export interface Handle<_Input, _Output, _Rpcs extends Rpc.Any> {
-  readonly pid: ID;
-  readonly parentId: ID | null;
-
-  /**
-   * Process definition key ({@link Operation.Durable.key}) for this process.
-   */
-  readonly key: string;
-
-  /**
-   * Parameters of the process.
-   */
-  readonly params: Params;
-
-  /**
-   * What the process is running on behalf of. See {@link Environment}.
-   */
-  readonly environment: Environment;
-
+/**
+ * A process: one running (or finished) instance of a durable operation, wherever its runtime runs.
+ *
+ * Its {@link Data} fields are plain values; the rest are live members that talk to the runtime.
+ * A process read from a tree or list is a cheap snapshot that reaches its runtime only once a
+ * live member is used (see {@link make}).
+ */
+export interface Process<_Input = any, _Output = any, _Rpcs extends Rpc.Any = any> extends Data {
   submitInput(input: _Input): Effect.Effect<void>;
   subscribeOutputs(): Stream.Stream<_Output>;
 
@@ -297,9 +293,9 @@ export interface Handle<_Input, _Output, _Rpcs extends Rpc.Any> {
    * the collector with {@link Effect.forkDetach}, not {@link Effect.forkChild} — the
    * parent scope closes as soon as `forEach` finishes and interrupts scoped forks
    * before live `pushEphemeral` events arrive. Interrupt the daemon fiber explicitly
-   * on dispose (see {@link ProcessOperationInvoker.fiberFromProcess}).
+   * on dispose.
    */
-  subscribeEphemeral(): Stream.Stream<Trace.Message>;
+  subscribeEphemeral(options?: SubscribeEphemeralOptions): Stream.Stream<Trace.Message>;
 
   terminate(): Effect.Effect<void>;
   readonly status: Status;
@@ -347,22 +343,23 @@ export interface Handle<_Input, _Output, _Rpcs extends Rpc.Any> {
    * Hydrates a dormant persisted process using the supplied definition.
    * No-op when the handle is already live (returns self).
    */
-  hydrate(definition: Operation.Durable<_Input, _Output, any, any>): Effect.Effect<Handle<_Input, _Output, _Rpcs>>;
+  hydrate(definition: Operation.Durable<_Input, _Output, any, any>): Effect.Effect<Process<_Input, _Output, _Rpcs>>;
 
   readonly rpc: RpcClient.RpcClient<_Rpcs>;
 }
 
-export namespace Handle {
-  // Widened to `any` Rpcs so the implemented `rpc: RpcClient<any>` is assignable
-  // regardless of a handle's concrete RPC group (variance, see design spec §4.4).
-  export type Any = Handle<any, any, any>;
-}
+// `any` Rpcs keeps every process assignable regardless of its concrete RPC group (variance, see design spec §4.4).
+export type Any = Process<any, any, any>;
 
 /**
  * Options for spawning a process.
  */
 export interface SpawnOptions {
-  /** Parent process ID — child inherits the parent's trace context. */
+  /**
+   * Parent process ID — child inherits the parent's trace context.
+   * Inside a process, its {@link ManagerService} defaults this to that process; pass `undefined`
+   * explicitly to spawn a detached process.
+   */
   readonly parentProcessId?: ID;
 
   /**
@@ -473,21 +470,82 @@ export interface Manager {
   spawn<I, O, Rpcs extends Rpc.Any = never>(
     definition: Operation.Durable<I, O, any, Rpcs>,
     options?: SpawnOptions & LocationOptions,
-  ): Effect.Effect<Handle<I, O, Rpcs>>;
+  ): Effect.Effect<Process<I, O, Rpcs>>;
 
   /**
-   * Handles on the processes at `options.location` matching `options`. Dormant entries require
-   * {@link Handle.hydrate} before inputs can be submitted.
+   * Live processes at `options.location` matching `options`. Dormant entries require
+   * {@link Process.hydrate} before inputs can be submitted.
    *
    * Dies when the location is a remote runtime that offers no process control.
    */
-  handles(options?: ListOptions & LocationOptions): Effect.Effect<readonly Handle.Any[]>;
+  handles(options?: ListOptions & LocationOptions): Effect.Effect<readonly Any[]>;
+
+  /**
+   * The live process `pid` at `options.location`. A process that has already exited
+   * replays its outputs, so its result stays readable after the exit.
+   *
+   * Dies when no such process is known, or when the location is a remote runtime that offers no
+   * process control.
+   */
+  attach<I, O, Rpcs extends Rpc.Any = never>(pid: ID, options?: LocationOptions): Effect.Effect<Process<I, O, Rpcs>>;
 }
 
+/**
+ * The first output of a single-output process (e.g. one running an operation), failing with the
+ * process's own cause when it fails without one.
+ */
+export const awaitOutput = <O>(handle: Process<any, O, any>): Effect.Effect<O> =>
+  handle.subscribeOutputs().pipe(
+    Stream.runHead,
+    Effect.flatMap(
+      Option.match({
+        onSome: Effect.succeed,
+        onNone: () => {
+          switch (handle.status.state) {
+            case State.FAILED:
+              return Effect.failCause(
+                handle.status.exit.pipe(
+                  Option.flatMap(Exit.getCause),
+                  Option.getOrElse(() => Cause.die('Operation failed with unknown error')),
+                ),
+              );
+            case State.TERMINATED:
+              return Effect.die('Operation was terminated');
+            case State.SUCCEEDED:
+              return Effect.die('Process produced no output');
+            default:
+              // Outputs close on a live process only when its manager suspends it (app shutdown): the
+              // wait was cut short rather than answered.
+              return Effect.interrupt;
+          }
+        },
+      }),
+    ),
+  );
+
 export class ManagerService extends Context.Service<ManagerService, Manager>()(
   '@dxos/compute/Process.ManagerService',
 ) {}
 
+/**
+ * Spawns `durable` through the ambient {@link ManagerService} and submits `input`; read its result with
+ * {@link awaitOutput}.
+ */
+export const spawn = <I, O, Rpcs extends Rpc.Any = never>(
+  durable: Operation.Durable<I, O, any, Rpcs>,
+  input: I,
+  options?: SpawnOptions & LocationOptions,
+): Effect.Effect<Process<I, O, Rpcs>, never, ManagerService> =>
+  Effect.gen(function* () {
+    const manager = yield* ManagerService;
+    const handle = yield* manager.spawn(durable, {
+      ...(durable.name !== undefined ? { name: durable.name } : {}),
+      ...options,
+    });
+    yield* handle.submitInput(input);
+    return handle;
+  });
+
 /**
  * New process is spawned.
  */

package/src/ShellService.ts

@@ -0,0 +1,71 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import type * as Scope from 'effect/Scope';
+
+import { BaseError } from '@dxos/errors';
+
+/** Raised when an operating-system process cannot be started. */
+export class ShellError extends BaseError.extend('ShellError', 'Shell command failed to start') {}
+
+export type SpawnOptions = {
+  /** Executable to run, resolved against `PATH` when not a path. */
+  readonly command: string;
+  readonly args?: readonly string[];
+  /** Working directory; the host's own when unset. */
+  readonly cwd?: string;
+  /** Added to the host's environment, overriding what it already has. */
+  readonly env?: Readonly<Record<string, string>>;
+};
+
+export type ExecOptions = Omit<SpawnOptions, 'command' | 'args'> & {
+  /** A bash script, run as `bash -c <script>`. */
+  readonly script: string;
+};
+
+export type ExecResult = {
+  /** `null` when a signal ended the command. */
+  readonly exitCode: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+/** A running operating-system process and its standard streams. */
+export interface Child {
+  readonly pid: number | undefined;
+  readonly stdin: WritableStream<Uint8Array>;
+  readonly stdout: ReadableStream<Uint8Array>;
+  readonly stderr: ReadableStream<Uint8Array>;
+  /** Completes with the exit code once the process exits; `null` when a signal ended it. */
+  readonly exited: Effect.Effect<number | null>;
+  /** Ends the process; a process that already exited is left as it is. */
+  readonly kill: Effect.Effect<void>;
+}
+
+export interface Service {
+  /**
+   * Starts `options.command` as an operating-system process. It is killed when the scope closes or
+   * when the compute process that owns this service ends, whichever comes first.
+   */
+  spawn(options: SpawnOptions): Effect.Effect<Child, ShellError, Scope.Scope>;
+  /** Runs a bash script to completion and collects its output. */
+  exec(options: ExecOptions): Effect.Effect<ExecResult, ShellError>;
+}
+
+/**
+ * Runs operating-system processes and bash commands for a compute process. Each compute process gets
+ * its own instance (process affinity), so nothing it started outlives it. Only a host that can start
+ * one provides it (the desktop app, the vite dev server, a CLI); a process that requires it runs nowhere else.
+ */
+export class ShellService extends Context.Service<ShellService, Service>()('@dxos/compute/ShellService') {}
+
+export const spawn = (options: SpawnOptions): Effect.Effect<Child, ShellError, ShellService | Scope.Scope> =>
+  ShellService.use((service) => service.spawn(options));
+
+export const exec = (options: ExecOptions): Effect.Effect<ExecResult, ShellError, ShellService> =>
+  ShellService.use((service) => service.exec(options));

package/src/errors.ts

@@ -67,6 +67,13 @@ export class InvalidOperationOutputError extends BaseError.extend(
 
 export class TriggerStateNotFoundError extends BaseError.extend('TriggerStateNotFound', 'Trigger state not found') {}
 
+/** A manual run was asked of a trigger that is switched off; nothing was dispatched. */
+export class TriggerDisabledError extends BaseError.extend('TriggerDisabledError', 'Trigger is disabled') {
+  constructor(triggerId: string) {
+    super({ context: { triggerId } });
+  }
+}
+
 /**
  * Raised when the upstream AI gateway responds with a structured JSON error envelope
  * (`{ "type": "error", "error": { "type": ..., "message": ... } }`). Surfaces as a typed

package/src/index.ts

@@ -18,6 +18,7 @@ export * as OperationRegistry from './OperationRegistry.ts';
 export * as Process from './Process.ts';
 export * as Runnable from './Runnable.ts';
 export * as ServiceResolver from './ServiceResolver.ts';
+export * as ShellService from './ShellService.ts';
 export * as SqlService from './SqlService.ts';
 export * as StorageService from './StorageService.ts';
 export * as Trace from './Trace.ts';

package/src/types/Project.ts

@@ -65,6 +65,17 @@ export class Project extends Type.makeObject<Project>(DXN.make('org.dxos.type.pr
     // TODO(burdon): Change to array? Move into taskSet?
     repo: Schema.optional(Ref.Ref(Repo.Repo).annotate({ title: 'Repository' })),
 
+    /**
+     * Repositories the project's coding agents work on. A cloud session checks each one out in its
+     * sandbox; a session on this computer works in the folder chosen for the project there.
+     */
+    repositories: Schema.optional(
+      Schema.Array(Ref.Ref(Repo.Repo)).annotate({
+        title: 'Repositories',
+        description: 'Checked out for coding agents that run in the cloud.',
+      }),
+    ),
+
     /** The default configuration (model, ...) for the sessions this project starts; a chat's own overrides it. */
     session: Schema.optional(SessionConfig.SessionConfig.pipe(Annotation.FormInputAnnotation.set(false))),
   }).pipe(

package/src/types/Skill.ts

@@ -121,8 +121,17 @@ export const Hook = Schema.Struct({
    * Must match the function's input schema.
    */
   input: Trigger.InputTemplate.pipe(Annotation.FormInputAnnotation.set(false), Schema.optional),
+
+  /**
+   * Run in the background (end-request only): the request settles without waiting for the hook, and
+   * the agent process awaits it before it finishes. For work the user should not wait on, e.g.
+   * reviewing the turn that just ended.
+   */
+  async: Schema.optional(Schema.Boolean.annotate({ title: 'Run in background' })),
 });
 
+export type Hook = Schema.Schema.Type<typeof Hook>;
+
 /**
  * Create a new Skill.
  * The `key` (and optional `version`) are stored in the object meta.

package/src/types/Trigger.ts

@@ -14,6 +14,7 @@ import { Annotation, DXN, Feed, Obj, type Query, QueryAST, Ref, Type } from '@dx
 import { OptionsAnnotationId } from '@dxos/echo/Format';
 import * as SchemaAST from '@dxos/effect/SchemaAST';
 
+import type { TriggerDisabledError } from '../errors.ts';
 import * as Runnable from '../Runnable.ts';
 import type * as TriggerEvent from './TriggerEvent.ts';
 
@@ -288,9 +289,9 @@ export interface InvokeOptions {
 }
 
 /**
- * Service for monitoring trigger dispatcher state.
+ * Observes and invokes the triggers registered with the dispatchers (local and edge).
  */
-export interface Monitor {
+export interface Manager {
   /**
    * Triggers actively registered in the dispatcher.
    * Could contain entries for both local and edge triggers, but only the edge ones are actually running.
@@ -303,15 +304,16 @@ export interface Monitor {
    * Invoke a trigger.
    * Available only for direct and timer triggers.
    * Invocation respects the trigger's concurrency limit.
+   * Fails with {@link TriggerDisabledError} for a trigger that is switched off.
    */
-  readonly invokeTrigger: (options: InvokeOptions) => Effect.Effect<void>;
+  readonly invokeTrigger: (options: InvokeOptions) => Effect.Effect<void, TriggerDisabledError>;
 }
 
 /**
- * Service for monitoring trigger executions.
+ * Service providing the {@link Manager}.
  */
-export class TriggerMonitorService extends Context.Service<TriggerMonitorService, Monitor>()(
-  '@dxos/functions/TriggerMonitorService',
+export class ManagerService extends Context.Service<ManagerService, Manager>()(
+  '@dxos/compute/Trigger.ManagerService',
 ) {}
 
-export { TriggerStateNotFoundError } from '../errors.ts';
+export { TriggerDisabledError, TriggerStateNotFoundError } from '../errors.ts';