@dxos/compute 0.9.0 → 0.9.1-staging.ee54ba693a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/compute",
-  "version": "0.9.0",
+  "version": "0.9.1-staging.ee54ba693a",
   "description": "Umbrella package for AI-aware DXOS compute primitives.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -18,6 +18,11 @@
       "types": "./dist/types/src/index.d.ts",
       "default": "./dist/lib/neutral/index.mjs"
     },
+    "./AgentService": {
+      "source": "./src/AgentService.ts",
+      "types": "./dist/types/src/AgentService.d.ts",
+      "default": "./dist/lib/neutral/AgentService.mjs"
+    },
     "./StorageService": {
       "source": "./src/StorageService.ts",
       "types": "./dist/types/src/StorageService.d.ts",
@@ -36,25 +41,26 @@
   ],
   "dependencies": {
     "@effect-atom/atom": "^0.5.3",
-    "@effect/platform": "0.96.1",
-    "@dxos/ai": "0.9.0",
-    "@dxos/echo": "0.9.0",
-    "@dxos/errors": "0.9.0",
-    "@dxos/effect": "0.9.0",
-    "@dxos/invariant": "0.9.0",
-    "@dxos/keys": "0.9.0",
-    "@dxos/log": "0.9.0",
-    "@dxos/protocols": "0.9.0",
-    "@dxos/schema": "0.9.0",
-    "@dxos/vendor-kbn-handlebars": "0.9.0"
+    "@effect/platform": "0.96.2",
+    "@effect/rpc": "0.75.1",
+    "@dxos/ai": "0.9.1-staging.ee54ba693a",
+    "@dxos/echo": "0.9.1-staging.ee54ba693a",
+    "@dxos/effect": "0.9.1-staging.ee54ba693a",
+    "@dxos/invariant": "0.9.1-staging.ee54ba693a",
+    "@dxos/keys": "0.9.1-staging.ee54ba693a",
+    "@dxos/errors": "0.9.1-staging.ee54ba693a",
+    "@dxos/log": "0.9.1-staging.ee54ba693a",
+    "@dxos/vendor-kbn-handlebars": "0.9.1-staging.ee54ba693a",
+    "@dxos/schema": "0.9.1-staging.ee54ba693a",
+    "@dxos/protocols": "0.9.1-staging.ee54ba693a"
   },
   "devDependencies": {
-    "effect": "3.21.3",
-    "vitest": "4.1.7",
-    "@dxos/echo-client": "0.9.0"
+    "effect": "3.21.4",
+    "vitest": "4.1.8",
+    "@dxos/echo-client": "0.9.1-staging.ee54ba693a"
   },
   "peerDependencies": {
-    "effect": "3.21.3"
+    "effect": "3.21.4"
   },
   "publishConfig": {
     "access": "public"

package/src/AgentService.ts

@@ -0,0 +1,90 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import type * as Stream from 'effect/Stream';
+
+import type { Database, Feed, Obj, Ref } from '@dxos/echo';
+import { DXN } from '@dxos/keys';
+
+import type * as Trace from './Trace';
+
+/**
+ * Service interface for the agent session manager.
+ * Implementation lives in @dxos/functions-runtime.
+ */
+export interface Service {
+  /**
+   * Gets or creates a session for a feed.
+   */
+  getSession: (feed: Feed.Feed, options?: GetSessionOptions) => Effect.Effect<Session>;
+
+  /**
+   * Hydrates agent processes persisted by a previous session.
+   * Each record is rehydrated with a fresh process built from the layer options.
+   */
+  hydrate: () => Effect.Effect<void>;
+}
+
+export class AgentService extends Context.Tag('@dxos/functions-runtime/AgentService')<AgentService, Service>() {}
+
+/**
+ * Handle to an agent session.
+ */
+export interface Session {
+  /**
+   * The feed that the session is associated with.
+   */
+  readonly feed: Feed.Feed;
+
+  /**
+   * Gets the context objects from the agent.
+   */
+  getContext: () => Effect.Effect<Ref.Ref<Obj.Unknown>[], never, Database.Service>;
+
+  /**
+   * Adds context objects to the agent.
+   */
+  addContext: (context: Ref.Ref<Obj.Unknown>[]) => Effect.Effect<void, never, Database.Service>;
+
+  /**
+   * Submits a prompt to the agent.
+   */
+  submitPrompt: (prompt: string) => Effect.Effect<void>;
+
+  /**
+   * Wait until agent has completed its work.
+   */
+  waitForCompletion: () => Effect.Effect<void>;
+
+  /**
+   * Terminates the agent process and clears its durable storage.
+   */
+  terminate: () => Effect.Effect<void>;
+
+  /**
+   * Subscribe to ephemeral trace events (e.g., streaming partial messages).
+   * Replays buffered events, then streams new ones until the process ends.
+   *
+   * When forking a collector from a short-lived parent (e.g. `useEffect` +
+   * `runPromise(Effect.forEach(subscribe))`), use {@link Effect.forkDaemon} so the
+   * stream survives after the parent scope closes; interrupt it on dispose.
+   */
+  subscribeEphemeral: () => Stream.Stream<Trace.Message>;
+}
+
+export const getSession = Effect.serviceFunctionEffect(AgentService, (service) => service.getSession);
+
+export const hydrate = Effect.serviceFunctionEffect(AgentService, (service) => service.hydrate);
+
+export interface GetSessionOptions {
+  readonly model?: DXN.DXN;
+  // The catalog's shared model ids are served by several providers, so the provider must accompany
+  // the model into the agent process — the id alone does not identify a resolver.
+  readonly provider?: DXN.DXN;
+  readonly systemPrompt?: string;
+}

package/src/Credential.ts

@@ -19,6 +19,9 @@ export type ServiceCredential = {
 
   // TODO(dmaretskyi): Build out.
   apiKey?: string;
+
+  /** Non-secret secondary identifier carried alongside the credential (e.g. an account id or report id). */
+  account?: string;
 };
 
 export class CredentialsService extends Context.Tag('@dxos/functions/CredentialsService')<

package/src/Instructions.ts

@@ -0,0 +1,73 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, DXN, Format, JsonSchema, Obj, Ref, Type } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+
+import * as Skill from './Skill';
+
+/**
+ * Prompt-based operation.
+ * May reference skills and additional context.
+ * Hidden from the navtree and object picker — accessed only through Routines.
+ */
+export class Instructions extends Type.makeObject<Instructions>(DXN.make('org.dxos.type.instructions', '0.1.0'))(
+  Schema.Struct({
+    name: Schema.optional(Schema.String),
+    description: Schema.optional(Schema.String),
+    input: JsonSchema.JsonSchema.pipe(Annotation.FormInputAnnotation.set(false)).annotations({
+      description: 'Input schema',
+    }),
+    output: JsonSchema.JsonSchema.pipe(Annotation.FormInputAnnotation.set(false)).annotations({
+      description: 'Output schema',
+    }),
+    text: Ref.Ref(Text.Text).pipe(
+      Format.FormatAnnotation.set(Format.TypeFormat.Markdown),
+      Schema.annotations({ title: 'Instructions', description: 'Describe what the agent should do in each session.' }),
+    ),
+    skills: Schema.Array(Ref.Ref(Skill.Skill)),
+    /**
+     * Context objects bound to the agent's session when this routine runs (sibling of `skills`).
+     * Generic `Ref.Ref(Obj.Unknown)` so any space object qualifies. Honored on every run path that
+     * executes a routine through the agent prompt, not only triggered automations.
+     */
+    objects: Schema.Array(Ref.Ref(Obj.Unknown)).pipe(Schema.annotations({ title: 'Objects' }), Schema.optional),
+  }).pipe(
+    Annotation.LabelAnnotation.set(['name']),
+    Annotation.IconAnnotation.set({ icon: 'ph--scroll--regular', hue: 'sky' }),
+    Annotation.HiddenAnnotation.set(true),
+  ),
+) {}
+
+export type MakeProps = {
+  name?: string;
+  description?: string;
+  input?: Schema.Schema.AnyNoContext;
+  output?: Schema.Schema.AnyNoContext;
+  text?: string;
+  skills?: Ref.Ref<Skill.Skill>[];
+  objects?: Ref.Ref<Obj.Unknown>[];
+};
+
+/** Creates an Instructions object with an owned Markdown `text` body (parented so it cascades and deep-clones). */
+export const make = ({ name, description, input, output, text, skills = [], objects }: MakeProps): Instructions => {
+  const body = Text.make({ content: text ?? '' });
+  const instructions = Obj.make(Instructions, {
+    name,
+    description,
+    input: JsonSchema.toJsonSchema(input ?? Schema.Void),
+    output: JsonSchema.toJsonSchema(output ?? Schema.Void),
+    text: Ref.make(body),
+    skills,
+    objects,
+  });
+  // The body is owned by the instructions: it cascade-deletes with it and is cloned alongside it under
+  // `Obj.clone(..., { deep: 'parent' })`.
+  Obj.setParent(body, instructions);
+  return instructions;
+};

package/src/McpServer.ts

@@ -9,7 +9,7 @@ import * as Schema from 'effect/Schema';
 /**
  * MCP server connection spec — the minimal fields needed to dial an MCP server.
  *
- * Used as a value type embedded in blueprints and passed to runtime session connect logic.
+ * Used as a value type embedded in skills and passed to runtime session connect logic.
  * The user-facing ECHO object (`@dxos/assistant-toolkit` `McpServer`) composes this struct
  * and adds instance-level fields (`name`, `enabled`) and ECHO annotations.
  */

package/src/Operation.test.ts

@@ -0,0 +1,39 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { DXN } from '@dxos/keys';
+
+import * as Operation from './Operation';
+
+const KEY = DXN.make('org.example.test.op');
+
+const makeOp = () => Operation.make({ input: Schema.Void, output: Schema.String, meta: { key: KEY, name: 'Test Op' } });
+
+describe('Operation visibility', () => {
+  test('operations are hidden by default', ({ expect }) => {
+    expect(Operation.isVisible(Operation.serialize(makeOp()))).toBe(false);
+  });
+
+  test('visible combinator marks an operation visible', ({ expect }) => {
+    expect(Operation.isVisible(Operation.serialize(makeOp().pipe(Operation.visible)))).toBe(true);
+  });
+
+  test('annotate does not mutate the input definition', ({ expect }) => {
+    const op = makeOp();
+    const annotated = op.pipe(Operation.visible);
+    expect(Operation.isVisible(Operation.serialize(annotated))).toBe(true);
+    // The original definition is untouched — combinators return a fresh value.
+    expect(Operation.isVisible(Operation.serialize(op))).toBe(false);
+  });
+
+  test('visible preserves the definition type so a handler still attaches', ({ expect }) => {
+    // Type-preservation is a compile-time guarantee; this asserts the value path also works.
+    const op = makeOp().pipe(Operation.visible, (op) => Operation.withHandler(op, () => Effect.succeed('ok')));
+    expect(Operation.isOperationWithHandler(op)).toBe(true);
+  });
+});

package/src/Operation.ts

@@ -9,10 +9,11 @@ import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import * as Option from 'effect/Option';
 import * as Pipeable from 'effect/Pipeable';
+import * as Schema from 'effect/Schema';
 import * as Schema$ from 'effect/Schema';
 import type * as Types from 'effect/Types';
 
-import { DXN, Annotation, JsonSchema, Migration, Obj, Ref, Type, type Key } from '@dxos/echo';
+import { Annotation, DXN, JsonSchema, type Key, Migration, Obj, Ref, Type } from '@dxos/echo';
 import type { URI } from '@dxos/keys';
 
 import type { NoHandlerError } from './errors';
@@ -299,46 +300,48 @@ export type InvokeRemote = <I, O, E>(
  * The registry `key` and `version` live in the object meta — access via
  * `Obj.getMeta(record).key` and `Obj.getMeta(record).version`.
  */
-export const PersistentOperation = Schema$.Struct({
-  name: Schema$.NonEmptyString,
+// TODO(dmaretskyi): Keep typename as 'org.dxos.type.function' (not 'operation') to maintain
+//  backward compatibility with existing data and avoid requiring data migration.
+export class PersistentOperation extends Type.makeObject<PersistentOperation>(
+  DXN.make('org.dxos.type.function', '0.2.0'),
+)(
+  Schema$.Struct({
+    name: Schema$.NonEmptyString,
 
-  description: Schema$.optional(Schema$.String),
+    description: Schema$.optional(Schema$.String),
 
-  /**
-   * ISO date string of the last deployment.
-   */
-  updated: Schema$.optional(Schema$.String),
+    /**
+     * ISO date string of the last deployment.
+     */
+    updated: Schema$.optional(Schema$.String),
 
-  // Reference to a source script if it exists within ECHO.
-  // TODO(burdon): Don't ref ScriptType directly (core).
-  source: Schema$.optional(Ref.Ref(Obj.Unknown)),
+    // Reference to a source script if it exists within ECHO.
+    // TODO(burdon): Don't ref ScriptType directly (core).
+    source: Schema$.optional(Ref.Ref(Obj.Unknown)),
 
-  inputSchema: Schema$.optional(JsonSchema.JsonSchema),
-  outputSchema: Schema$.optional(JsonSchema.JsonSchema),
+    inputSchema: Schema$.optional(JsonSchema.JsonSchema),
+    outputSchema: Schema$.optional(JsonSchema.JsonSchema),
 
-  /**
-   * List of required services.
-   * Match the Context.Tag keys of the FunctionServices variants.
-   */
-  services: Schema$.optional(Schema$.Array(Schema$.String)),
+    /**
+     * List of required services.
+     * Match the Context.Tag keys of the FunctionServices variants.
+     */
+    services: Schema$.optional(Schema$.Array(Schema$.String)),
 
-  // Local binding to a function name.
-  // TODO(dmaretskyi): Add this field to Operation.Definition.
-  binding: Schema$.optional(Schema$.String),
+    // Local binding to a function name.
+    // TODO(dmaretskyi): Add this field to Operation.Definition.
+    binding: Schema$.optional(Schema$.String),
 
-  /**
-   * Phosphor icon identifier in `ph--<name>--<variant>` format (e.g. `ph--file-text--regular`).
-   */
-  icon: Schema$.optional(Schema$.String),
-}).pipe(
-  Annotation.LabelAnnotation.set(['name']),
-  Annotation.IconAnnotation.set({ icon: 'ph--function--regular', hue: 'blue' }),
-  Annotation.HiddenAnnotation.set(true),
-  // TODO(dmaretskyi): Keep typename as 'org.dxos.type.function' (not 'operation') to maintain
-  //  backward compatibility with existing data and avoid requiring data migration.
-  Type.makeObject(DXN.make('org.dxos.type.function', '0.2.0')),
-);
-export type PersistentOperation = Type.InstanceType<typeof PersistentOperation>;
+    /**
+     * Phosphor icon identifier in `ph--<name>--<variant>` format (e.g. `ph--file-text--regular`).
+     */
+    icon: Schema$.optional(Schema$.String),
+  }).pipe(
+    Annotation.LabelAnnotation.set(['name']),
+    Annotation.IconAnnotation.set({ icon: 'ph--function--regular', hue: 'blue' }),
+    Annotation.HiddenAnnotation.set(true),
+  ),
+) {}
 
 const FUNCTION_META_KEY = 'org.dxos.service.function';
 
@@ -429,20 +432,46 @@ export const setFrom = (target: PersistentOperation, source: PersistentOperation
  * Defined locally to avoid a core dependency on UI translation packages; structurally compatible with
  * the app-level `Label` type so values flow into UI toasts unchanged.
  */
-export type Label = string | [string, { ns: string | readonly string[]; count?: number; defaultValue?: string }];
+export const Label = Schema.Union(
+  Schema.String,
+  // `Schema.mutable` mirrors the app-level `Label` (whose tuple is mutable), so decoded values are
+  // assignable to UI toast `title`/`label` slots without a readonly-vs-mutable tuple mismatch.
+  Schema.mutable(
+    Schema.Tuple(
+      Schema.String,
+      Schema.mutable(
+        Schema.Struct({
+          ns: Schema.String,
+          count: Schema.optional(Schema.Number),
+          defaultValue: Schema.optional(Schema.String),
+        }),
+      ),
+    ),
+  ),
+);
+export type Label = Schema.Schema.Type<typeof Label>;
 
 /**
  * Per-phase user notification messages for an invocation.
  * A phase is notified to the user iff its message is provided; messages are translatable {@link Label}s.
  */
-export interface NotifyOptions {
+export const NotifyOptions = Schema.Struct({
   /** Shown when the invocation starts. */
-  start?: Label;
+  start: Schema.optional(Label),
   /** Shown when the invocation succeeds. */
-  success?: Label;
+  success: Schema.optional(Label),
   /** Shown when the invocation fails. */
-  error?: Label;
-}
+  error: Schema.optional(Label),
+});
+export type NotifyOptions = Schema.Schema.Type<typeof NotifyOptions>;
+
+/**
+ * Annotation that configures the process to notify the user at the given invocation phases.
+ */
+export const NotifyOptionsAnnotation = Annotation.make({
+  id: 'org.dxos.operation.notify-options',
+  schema: NotifyOptions,
+});
 
 /**
  * Options for operation invocation.
@@ -460,7 +489,7 @@ export interface InvokeOptions {
    * URI of the conversation feed (queue) — today always an EID, but typed as
    * `URI.URI` to accommodate future entity-kind extensions. Narrow with `EID.parse`
    * at the point of use.
-   * Passed to the process environment so nested operations can resolve AiContext.Service and related services.
+   * Passed to the process environment so nested operations can resolve HarnessService and related services.
    */
   conversation?: URI.URI;
   /**
@@ -487,6 +516,50 @@ export const isIdempotent = (op: Definition.Any): boolean =>
     ? Option.getOrElse(Annotation.getDictionary(op.meta.annotations, IdempotentAnnotation), () => false)
     : false;
 
+/**
+ * Attaches an annotation to an operation definition, returning a new definition.
+ * Combinators never mutate their input — operation definitions are module-level singletons
+ * shared across handler sets, skills, and the registry, so a fresh value keeps the
+ * annotated definition distinct from any other reference to the original.
+ *
+ * Type-preserving: an annotation does not change the operation's input/output/service types, so the
+ * returned definition keeps `Def` (preserving `withHandler` inference and downstream usage).
+ */
+export const annotate =
+  <T>(annotation: Annotation.Annotation<T>, value: T) =>
+  <Def extends Definition.Any>(op: Def): Def => {
+    const annotations = { ...(op.meta.annotations ?? {}) };
+    Annotation.setDictionary(annotations, annotation, value);
+    // The spread reconstructs the same shape with only `meta.annotations` changed; the checker can't
+    // track the branded variance symbol through the untyped dictionary mutation, so reassert `Def`.
+    return { ...op, meta: { ...op.meta, annotations } } as Def;
+  };
+
+/**
+ * Marks an operation as visible on user-facing operation surfaces (trigger/automation pickers,
+ * manual invocation). Absent ⇒ internal: invoked programmatically by plugins and hidden from pickers.
+ *
+ * Polarity is inverted from the schema-level `HiddenAnnotation` (default visible): operations are
+ * hidden by default, since most are internal plugin machinery and only a minority are user-facing.
+ */
+export const VisibleAnnotation = Annotation.make({
+  id: 'org.dxos.operation.visible',
+  schema: Schema$.Boolean,
+});
+
+/**
+ * Pipeable combinator that marks an operation visible. Apply at the definition site:
+ * `Operation.make({ ... }).pipe(Operation.visible)`.
+ */
+export const visible = annotate(VisibleAnnotation, true);
+
+/**
+ * Returns true when an operation is annotated as visible on user-facing surfaces (trigger/automation
+ * pickers, manual invocation). Reads from the persisted operation — the form every consumer holds.
+ */
+export const isVisible = (op: PersistentOperation): boolean =>
+  Option.getOrElse(Annotation.get(op, VisibleAnnotation), () => false);
+
 /**
  * Operation service interface - provides unified access to operation invocation and scheduling.
  * This service is automatically provided to operation handlers.
@@ -605,19 +678,22 @@ export const withInvocationOptions = (options: InvokeOptions): Layer.Layer<Servi
  * Persistent operation schema v0.1.0 — `key` and `version` are stored as data properties.
  * @deprecated Use {@link PersistentOperation} (v0.2.0) instead; the `key` and `version` now live in the object meta.
  */
-export const PersistentOperation_v0_1_0 = Schema$.Struct({
-  key: Schema$.optional(Schema$.String),
-  name: Schema$.NonEmptyString,
-  version: Schema$.String,
-  description: Schema$.optional(Schema$.String),
-  updated: Schema$.optional(Schema$.String),
-  source: Schema$.optional(Ref.Ref(Obj.Unknown)),
-  inputSchema: Schema$.optional(JsonSchema.JsonSchema),
-  outputSchema: Schema$.optional(JsonSchema.JsonSchema),
-  services: Schema$.optional(Schema$.Array(Schema$.String)),
-  binding: Schema$.optional(Schema$.String),
-}).pipe(Type.makeObject(DXN.make('org.dxos.type.function', '0.1.0')));
-export type PersistentOperation_v0_1_0 = Type.InstanceType<typeof PersistentOperation_v0_1_0>;
+export class PersistentOperation_v0_1_0 extends Type.makeObject<PersistentOperation_v0_1_0>(
+  DXN.make('org.dxos.type.function', '0.1.0'),
+)(
+  Schema$.Struct({
+    key: Schema$.optional(Schema$.String),
+    name: Schema$.NonEmptyString,
+    version: Schema$.String,
+    description: Schema$.optional(Schema$.String),
+    updated: Schema$.optional(Schema$.String),
+    source: Schema$.optional(Ref.Ref(Obj.Unknown)),
+    inputSchema: Schema$.optional(JsonSchema.JsonSchema),
+    outputSchema: Schema$.optional(JsonSchema.JsonSchema),
+    services: Schema$.optional(Schema$.Array(Schema$.String)),
+    binding: Schema$.optional(Schema$.String),
+  }),
+) {}
 
 /**
  * Migration from {@link PersistentOperation_v0_1_0} (v0.1.0) to {@link PersistentOperation} (v0.2.0).