Operations

An operation is an action with a name, a typed input and a typed output, defined once and run from anywhere in an app, by people and by agents.

Model

An operation definition has a key (a DXN), metadata for people and agents, and schemas for its input and output. A handler is an Effect that takes the input and returns the output. Definitions and handlers are separate values, so a plugin can export a definition for other plugins to call without exposing how it runs.

src/types/StashedLinkOperation.ts

import * as Schema from 'effect/Schema';

import * as Operation from '@dxos/compute/Operation';
import { Database, DXN, Ref } from '@dxos/echo';

import { StashedLink } from './StashedLink.ts';

export const MarkRead = Operation.make({
  meta: {
    key: DXN.make('com.example.operation.stashedLink.markRead'),
    name: 'Mark as read',
    description: 'Mark a link as read.',
    icon: 'ph--check-circle--regular',
  },
  // The handler resolves the reference in the link's space.
  services: [Database.Service],
  input: Schema.Struct({
    link: Ref.Ref(StashedLink).annotate({
      description: 'The link that was read.',
    }),
  }),
  output: Schema.Void,
});

Plugins contribute handlers in an operation handler set through the OperationHandler capability. The operation invoker looks up the handler by the definition’s key and runs it. Any module, handler or graph action can invoke an operation with Operation.invoke; a component uses useOperation.

import * as Effect from 'effect/Effect';
import * as Operation from '@dxos/compute/Operation';
import { Ref } from '@dxos/echo';
import { type StashedLink } from './src/types/StashedLink.ts';
import { MarkRead } from './src/types/StashedLinkOperation.ts';

// Any module, handler or action can run an operation by its definition.
export const markRead = (link: StashedLink) =>
  Operation.invoke(MarkRead, { link: Ref.make(link) }).pipe(
    Effect.catchTag('NoHandlerError', () => Effect.succeed(undefined)),
  );

A skill hands operations to the assistant. It is a name, instructions, and a list of operations that become the assistant’s tools; a plugin contributes it through AppCapabilities.SkillDefinition.

src/skills/StashSkill.ts

import * as Skill from '@dxos/compute/Skill';
import * as Template from '@dxos/compute/Template';

import { MarkRead } from '../types/StashedLinkOperation.ts';

export const key = 'com.example.skill.stash';

export const make = (): Skill.Skill =>
  Skill.make({
    key,
    name: 'Stash',
    tools: Skill.toolDefinitions({ operations: [MarkRead] }),
    instructions: Template.make({
      source:
        'When the user says they have read a page they stashed, find its ' +
        'link and mark it as read.',
    }),
  });

Stash’s Operations module in the inspector runs Mark as read from a form built from its input schema:

Behavior

• One definition serves three callers. A button invokes it through a hook. The command palette lists it. A skill hands it to the assistant as a tool, and the assistant reads the schema descriptions to fill in the input. None of the three needs code of its own.
• The invoker validates the input against the schema before the handler runs, and the output after.
• Errors are typed. A handler fails with tagged errors that a caller catches by tag, and invoking an operation that no plugin handles fails with NoHandlerError.
• An operation can be undone. A plugin contributes an UndoMapping that names the operation’s inverse and derives the inverse’s input from the forward input and output; the app records each undoable invocation and offers to undo it.

import * as Effect from 'effect/Effect';
import * as Schema from 'effect/Schema';
import * as ActivationEvents from '@dxos/app-framework/ActivationEvents';
import * as Capabilities from '@dxos/app-framework/Capabilities';
import * as Capability from '@dxos/app-framework/Capability';
import * as Operation from '@dxos/compute/Operation';
import { DXN } from '@dxos/echo';

const Rename = Operation.make({
  meta: {
    key: DXN.make('com.example.operation.rename'),
    name: 'Rename',
  },
  input: Schema.Struct({ id: Schema.String, name: Schema.String }),
  output: Schema.Struct({ previous: Schema.String }),
});

// The inverse is the same operation with the previous name.
export const RenameUndoModule = Capability.inlineModule(
  'RenameUndo',
  {
    provides: [Capabilities.UndoMapping],
    activatesOn: ActivationEvents.Startup,
  },
  () =>
    Effect.succeed(
      Capability.contribute(Capabilities.UndoMapping, [
        {
          operation: Rename,
          inverse: Rename,
          deriveContext: (input, output) => ({
            id: input.id,
            name: output.previous,
          }),
          message: 'Renamed',
        },
      ]),
    ),
);

• Handlers load lazily. A lazy handler set names each handler’s module, and the framework imports it the first time the operation is invoked.
• The App Toolkit defines operations every plugin can call. LayoutOperation.Open opens items by path, LayoutOperation.Close closes them, and SpaceOperation.AddObject adds an object to a space.

Limits

• A handler runs with the services its definition declares, plus the operation service for invoking other operations. It does not get the React tree.
• An operation’s input must be serializable for the assistant to call it. Pass objects by reference where the caller is an agent.
• Undo replays the inverse operation; it does not restore a snapshot. An operation whose effect cannot be inverted from its input and output is not undoable.