@dxos/assistant-toolkit 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/skills/alarm/operations/set-alarm.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Clock from 'effect/Clock';
+import * as DateTime from 'effect/DateTime';
+import * as Effect from 'effect/Effect';
+import * as Either from 'effect/Either';
+
+import { Harness } from '@dxos/assistant';
+import { Operation } from '@dxos/compute';
+
+import { SetAlarm } from './definitions';
+import { resolveWakeAt } from './resolve-wake-at';
+
+/**
+ * Schedules a self-wake on the owning host via {@link Harness.setAlarm}. The host delivers the
+ * (optional) reminder message when the alarm fires.
+ */
+export default SetAlarm.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ in: inDuration, at, message }) {
+      const now = yield* Clock.currentTimeMillis;
+      const resolved = resolveWakeAt({ in: inDuration, at }, now);
+      if (Either.isLeft(resolved)) {
+        return resolved.left;
+      }
+      const wakeAt = DateTime.unsafeMake(resolved.right);
+      yield* Harness.setAlarm({ at: wakeAt, message: message ?? null });
+      return `Alarm scheduled to wake you at ${new Date(resolved.right).toISOString()}.`;
+    }),
+  ),
+);

package/src/skills/alarm/skill.test.ts

@@ -0,0 +1,128 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Either from 'effect/Either';
+
+import { Operation, Skill } from '@dxos/compute';
+import { Feed, Obj } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { AgentService } from '@dxos/functions-runtime';
+import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
+import { EntityId } from '@dxos/keys';
+import { Organization } from '@dxos/types';
+
+import { AlarmHandlers } from './operations';
+import { SetAlarm } from './operations/definitions';
+import { resolveWakeAt } from './operations/resolve-wake-at';
+import AlarmSkill from './skill';
+
+EntityId.dangerouslyDisableRandomness();
+
+const NOW = new Date('2026-06-04T12:00:00.000Z').getTime();
+
+const TestLayer = AssistantTestLayer({
+  types: [Organization.Organization, Feed.Feed, Skill.Skill],
+  operationHandlers: AlarmHandlers,
+  skills: [AlarmSkill.make()],
+  disableLlmMemoization: true,
+});
+
+describe('Alarm skill', () => {
+  // The set-alarm operation resolves the wake time; cover the parsing seam directly.
+  describe('resolveWakeAt', () => {
+    it('resolves an absolute "at" timestamp', ({ expect }) => {
+      const at = '2026-06-04T18:00:00.000Z';
+      const result = resolveWakeAt({ at }, NOW);
+      expect(Either.isRight(result)).toBe(true);
+      expect(Either.getOrThrow(result)).toBe(new Date(at).getTime());
+    });
+
+    it('resolves a relative "in" duration', ({ expect }) => {
+      const result = resolveWakeAt({ in: '5 minutes' }, NOW);
+      expect(Either.isRight(result)).toBe(true);
+      expect(Either.getOrThrow(result)).toBe(NOW + 5 * 60 * 1000);
+    });
+
+    it('rejects an invalid "at" timestamp', ({ expect }) => {
+      expect(Either.isLeft(resolveWakeAt({ at: 'not-a-date' }, NOW))).toBe(true);
+    });
+
+    it('rejects an invalid "in" duration', ({ expect }) => {
+      expect(Either.isLeft(resolveWakeAt({ in: 'whenever' }, NOW))).toBe(true);
+    });
+
+    it('rejects specifying both "in" and "at"', ({ expect }) => {
+      expect(Either.isLeft(resolveWakeAt({ in: '5 minutes', at: '2026-06-04T18:00:00.000Z' }, NOW))).toBe(true);
+    });
+
+    it('rejects specifying neither "in" nor "at"', ({ expect }) => {
+      expect(Either.isLeft(resolveWakeAt({}, NOW))).toBe(true);
+    });
+  });
+
+  // The set-alarm operation reaches the live host through HarnessService Tier B. createSession spawns
+  // an AgentProcess stamped as the harness host, so invoking the operation against that conversation
+  // dispatches over the process RPC loopback to the host's AlarmManager (no LLM turn required).
+  describe('set-alarm operation (Tier B)', () => {
+    it.scoped(
+      'arms a self-wake on the owning host for a relative duration',
+      Effect.fnUntraced(
+        function* ({ expect }) {
+          const agent = yield* AgentService.createSession({ skills: [AlarmSkill.make()] });
+          const conversation = Obj.getURI(agent.feed);
+
+          const result = yield* Operation.invoke(SetAlarm, { in: '1 hour', message: 'finish the report' }).pipe(
+            Effect.provide(Operation.withInvocationOptions({ conversation })),
+          );
+
+          // A success message (rather than a NotSupportedError) proves the operation resolved the live
+          // host and the Tier B RPC armed the alarm. Fire timing is covered by the AlarmManager unit
+          // tests and the process control-surface test in functions-runtime.
+          expect(result).toContain('Alarm scheduled to wake you at');
+        },
+        Effect.provide(TestLayer),
+        TestHelpers.provideTestContext,
+      ),
+    );
+
+    it.scoped(
+      'arms a self-wake on the owning host for an absolute time',
+      Effect.fnUntraced(
+        function* ({ expect }) {
+          const agent = yield* AgentService.createSession({ skills: [AlarmSkill.make()] });
+          const conversation = Obj.getURI(agent.feed);
+
+          const at = '2026-06-04T18:00:00.000Z';
+          const result = yield* Operation.invoke(SetAlarm, { at }).pipe(
+            Effect.provide(Operation.withInvocationOptions({ conversation })),
+          );
+
+          expect(result).toBe(`Alarm scheduled to wake you at ${at}.`);
+        },
+        Effect.provide(TestLayer),
+        TestHelpers.provideTestContext,
+      ),
+    );
+
+    it.scoped(
+      'reports invalid input without arming an alarm',
+      Effect.fnUntraced(
+        function* ({ expect }) {
+          const agent = yield* AgentService.createSession({ skills: [AlarmSkill.make()] });
+          const conversation = Obj.getURI(agent.feed);
+
+          const result = yield* Operation.invoke(SetAlarm, { in: 'whenever' }).pipe(
+            Effect.provide(Operation.withInvocationOptions({ conversation })),
+          );
+
+          expect(result).toContain('Invalid');
+        },
+        Effect.provide(TestLayer),
+        TestHelpers.provideTestContext,
+      ),
+    );
+  });
+});

package/src/skills/alarm/skill.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Skill } from '@dxos/compute';
+import { Ref } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+import { GetCurrentDate, SetAlarm } from './operations/definitions';
+
+const SKILL_KEY = 'org.dxos.skill.alarm';
+
+const instructions = trim`
+  You can schedule an alarm to wake yourself up in the future and continue working.
+  When the alarm fires you receive a prompt carrying any reminder you set.
+  Read the current time before computing an absolute wake time.
+`;
+
+const make = () =>
+  Skill.make({
+    key: SKILL_KEY,
+    name: 'Alarm',
+    description: 'Schedule a self-wake and inspect the current time.',
+    agentCanEnable: true,
+    instructions: {
+      source: Ref.make(Text.make({ content: instructions })),
+    },
+    tools: Skill.toolDefinitions({ operations: [SetAlarm, GetCurrentDate] }),
+  });
+
+const skill: Skill.Definition = {
+  key: SKILL_KEY,
+  make,
+};
+
+export default skill;

package/src/skills/automation/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { default as AutomationSkill } from './skill';

package/src/{blueprints/automation/blueprint.ts → skills/automation/skill.ts}

@@ -2,12 +2,12 @@
 // Copyright 2026 DXOS.org
 //
 
-import { Blueprint, Trigger, Operation } from '@dxos/compute';
+import { Operation, Skill, Trigger } from '@dxos/compute';
 import { Ref, Type } from '@dxos/echo';
 import { Text } from '@dxos/schema';
 import { trim } from '@dxos/util';
 
-const BLUEPRINT_KEY = 'dxos.org/blueprint/automation';
+const SKILL_KEY = 'org.dxos.skill.automation';
 
 const instructions = trim`
   Automation allows you to automatically initiate actions based on events.
@@ -47,7 +47,7 @@ const instructions = trim`
   ## Editing triggers
 
   Triggers are represented as objects of type ${Type.getTypename(Trigger.Trigger)}.
-  You need access to the Database blueprint to manipulate triggers.
+  You need access to the Database skill to manipulate triggers.
   Read trigger schema before manipulating triggers.
   Having a Trigger object in the database is enough to setup an automation. 
 
@@ -88,8 +88,8 @@ const instructions = trim`
 `;
 
 const make = () =>
-  Blueprint.make({
-    key: BLUEPRINT_KEY,
+  Skill.make({
+    key: SKILL_KEY,
     name: 'Triggers',
     description: 'Trigger management and automation.',
     instructions: {
@@ -97,9 +97,9 @@ const make = () =>
     },
   });
 
-const blueprint: Blueprint.Definition = {
-  key: BLUEPRINT_KEY,
+const skill: Skill.Definition = {
+  key: SKILL_KEY,
   make,
 };
 
-export default blueprint;
+export default skill;

package/src/skills/browser/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { default as BrowserSkill } from './skill';

package/src/{blueprints/browser/blueprint.test.ts → skills/browser/skill.test.ts}

@@ -7,29 +7,29 @@ import * as Effect from 'effect/Effect';
 
 import { MemoizedAiService } from '@dxos/ai/testing';
 import { SpaceProperties } from '@dxos/client-protocol';
-import { Blueprint, OperationHandlerSet } from '@dxos/compute';
+import { OperationHandlerSet, Skill } from '@dxos/compute';
 import { Collection, Database, Feed, Query } from '@dxos/echo';
 import { TestHelpers } from '@dxos/effect/testing';
 import { AgentService } from '@dxos/functions-runtime';
 import { AssistantTestLayerWithTriggers } from '@dxos/functions-runtime/testing';
 import { EntityId } from '@dxos/keys';
 import { log } from '@dxos/log';
-import { MarkdownBlueprint } from '@dxos/plugin-markdown';
+import { MarkdownSkill } from '@dxos/plugin-markdown';
 import { Markdown } from '@dxos/plugin-markdown';
 import { MarkdownOperationHandlerSet } from '@dxos/plugin-markdown/plugin';
 import { WithProperties } from '@dxos/plugin-markdown/testing';
 import { Person } from '@dxos/types';
 
-import { DatabaseBlueprint, DatabaseHandlers } from '../database';
-import BrowserBlueprint from './blueprint';
+import { DatabaseHandlers, DatabaseSkill } from '../database';
+import BrowserSkill from './skill';
 
 EntityId.dangerouslyDisableRandomness();
 
 const TestLayer = AssistantTestLayerWithTriggers({
   aiServicePreset: 'edge-remote',
   operationHandlers: OperationHandlerSet.merge(DatabaseHandlers, MarkdownOperationHandlerSet),
-  types: [Blueprint.Blueprint, Person.Person, Markdown.Document, SpaceProperties, Collection.Collection, Feed.Feed],
-  blueprints: [BrowserBlueprint.make(), MarkdownBlueprint.make(), DatabaseBlueprint.make()],
+  types: [Skill.Skill, Person.Person, Markdown.Document, SpaceProperties, Collection.Collection, Feed.Feed],
+  skills: [BrowserSkill.make(), MarkdownSkill.make(), DatabaseSkill.make()],
   tracing: 'pretty',
 });
 
@@ -40,7 +40,7 @@ describe('Browser', { tags: ['llm'] }, () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [BrowserBlueprint.make(), MarkdownBlueprint.make(), DatabaseBlueprint.make()],
+          skills: [BrowserSkill.make(), MarkdownSkill.make(), DatabaseSkill.make()],
         });
         yield* agent.submitPrompt(`
           Scrape effect blog at https://effect.website/blog and find the content of last 3 articles.

package/src/{blueprints/browser/blueprint.ts → skills/browser/skill.ts}

@@ -2,12 +2,12 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Blueprint } from '@dxos/compute';
+import { Skill } from '@dxos/compute';
 import { Ref } from '@dxos/echo';
 import { Text } from '@dxos/schema';
 import { trim } from '@dxos/util';
 
-const BLUEPRINT_KEY = 'org.dxos.blueprint.browser';
+const SKILL_KEY = 'org.dxos.skill.browser';
 
 const instructions = trim`
   You are able to connect and use a virtual browser with persistent session.
@@ -15,8 +15,8 @@ const instructions = trim`
 `;
 
 const make = () =>
-  Blueprint.make({
-    key: BLUEPRINT_KEY,
+  Skill.make({
+    key: SKILL_KEY,
     name: 'Browser',
     description: 'Access to a real isolated browser.',
     agentCanEnable: true,
@@ -32,9 +32,9 @@ const make = () =>
     ],
   });
 
-const blueprint: Blueprint.Definition = {
-  key: BLUEPRINT_KEY,
+const skill: Skill.Definition = {
+  key: SKILL_KEY,
   make,
 };
 
-export default blueprint;
+export default skill;

package/src/skills/connectors/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { default as ConnectorsSkill } from './skill';

package/src/skills/connectors/skill.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Skill } from '@dxos/compute';
+import { Ref } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+const SKILL_KEY = 'org.dxos.skill.connectors';
+
+/**
+ * Instructs the model to surface a connector prompt when a request needs a service the user has not
+ * connected, rather than failing silently. The prompt is rendered inline in the conversation by the
+ * `integration-prompt` surface, which offers to authenticate the matching connector.
+ */
+const instructions = trim`
+  Users connect external services (such as Gmail, Slack, GitHub, Linear, and Discord) through connectors.
+  A service is available to you only when a connection to it already exists in the current space.
+
+  When a request needs a service that is not connected, DO NOT fail, refuse, or apologize. Instead, render
+  a connector prompt so the user can connect it inline. Emit a self-closing surface tag with the
+  'integration-prompt' role and the service's domain:
+
+  <surface role='integration-prompt' data='{"service":"gmail.com"}' />
+
+  Use the service's domain as the 'service' value (for example 'gmail.com', 'slack.com', 'github.com').
+  Emit the surface once, then briefly tell the user that connecting the service will let you continue.
+`;
+
+const make = () =>
+  Skill.make({
+    key: SKILL_KEY,
+    name: 'Connectors',
+    description: 'Prompt the user to connect external services when a connector is required but unavailable.',
+    agentCanEnable: true,
+    instructions: {
+      source: Ref.make(Text.make({ content: instructions })),
+    },
+  });
+
+const skill: Skill.Definition = {
+  key: SKILL_KEY,
+  make,
+};
+
+export default skill;

package/src/{blueprints → skills}/database/index.ts

@@ -2,5 +2,5 @@
 // Copyright 2025 DXOS.org
 //
 
-export { default as DatabaseBlueprint } from './blueprint';
+export { default as DatabaseSkill } from './skill';
 export { DatabaseHandlers, DatabaseOperations } from './operations';

package/src/{blueprints → skills}/database/operations/context-add.ts

@@ -4,7 +4,7 @@
 
 import * as Effect from 'effect/Effect';
 
-import { AiContext } from '@dxos/assistant';
+import { Harness } from '@dxos/assistant';
 import { Operation } from '@dxos/compute';
 
 import { ContextAdd } from './definitions';
@@ -12,10 +12,10 @@ import { ContextAdd } from './definitions';
 export default ContextAdd.pipe(
   Operation.withHandler(
     Effect.fn(function* ({ obj }) {
-      const { binder } = yield* AiContext.Service;
+      const sessionBinder = yield* Harness.binder;
       yield* Effect.promise(() =>
-        binder.bind({
-          blueprints: [],
+        sessionBinder.bind({
+          skills: [],
           objects: [obj],
         }),
       );

package/src/{blueprints → skills}/database/operations/context-remove.ts

@@ -4,7 +4,7 @@
 
 import * as Effect from 'effect/Effect';
 
-import { AiContext } from '@dxos/assistant';
+import { Harness } from '@dxos/assistant';
 import { Operation } from '@dxos/compute';
 
 import { ContextRemove } from './definitions';
@@ -12,13 +12,13 @@ import { ContextRemove } from './definitions';
 export default ContextRemove.pipe(
   Operation.withHandler(
     Effect.fn(function* ({ obj }) {
-      const { binder } = yield* AiContext.Service;
+      const sessionBinder = yield* Harness.binder;
       yield* Effect.promise(() =>
-        binder.unbind({
-          blueprints: [],
+        sessionBinder.unbind({
+          skills: [],
           objects: [obj],
         }),
       );
-    }) as any,
+    }),
   ),
 );

package/src/{blueprints → skills}/database/operations/definitions.ts

@@ -4,7 +4,7 @@
 
 import * as Schema from 'effect/Schema';
 
-import { AiContext } from '@dxos/assistant';
+import { Harness } from '@dxos/assistant';
 import { Operation } from '@dxos/compute';
 import { Database, Obj, Ref, Relation, Tag, Type } from '@dxos/echo';
 import { DXN } from '@dxos/keys';
@@ -234,7 +234,7 @@ export const ContextAdd = Operation.make({
     }),
   }),
   output: Schema.Void,
-  services: [AiContext.Service],
+  services: [Harness.HarnessService],
 });
 
 export const ContextRemove = Operation.make({
@@ -253,7 +253,7 @@ export const ContextRemove = Operation.make({
     }),
   }),
   output: Schema.Void,
-  services: [AiContext.Service],
+  services: [Harness.HarnessService],
 });
 
 export const RelationCreate = Operation.make({

package/src/{blueprints → skills}/database/operations/query.ts

@@ -5,7 +5,7 @@
 import * as Effect from 'effect/Effect';
 
 import { Operation } from '@dxos/compute';
-import { Database, Entity, Filter, Obj, Query as EchoQuery, Scope, Type } from '@dxos/echo';
+import { Database, Query as EchoQuery, Entity, Filter, Obj, Scope, Type } from '@dxos/echo';
 
 import { Query } from './definitions';
 

package/src/{blueprints → skills}/database/operations/relation-create.ts

@@ -7,6 +7,7 @@ import * as Effect from 'effect/Effect';
 import { Operation } from '@dxos/compute';
 import { Database, Entity, Filter, Query, Relation, Scope, Type } from '@dxos/echo';
 import { invariant } from '@dxos/invariant';
+import { safeParseJson } from '@dxos/util';
 
 import { RelationCreate } from './definitions';
 
@@ -23,11 +24,18 @@ export default RelationCreate.pipe(
 
       const sourceObj = yield* Database.load(source);
       const targetObj = yield* Database.load(target);
+      // A stringified non-object (e.g. '"abc"' or '[1,2]') parses successfully but must not be
+      // spread onto the relation; only a plain object contributes properties.
+      const parsedProperties = typeof properties === 'string' ? safeParseJson(properties, {}) : properties;
+      const relationProperties =
+        parsedProperties !== null && typeof parsedProperties === 'object' && !Array.isArray(parsedProperties)
+          ? parsedProperties
+          : {};
       const relation = db.add(
         Relation.make(schema, {
           [Relation.Source]: sourceObj,
           [Relation.Target]: targetObj,
-          ...properties,
+          ...relationProperties,
         }),
       );
       return Entity.toJSON(relation);

package/src/{blueprints → skills}/database/operations/schema-list.ts

@@ -4,13 +4,13 @@
 
 import * as Effect from 'effect/Effect';
 
-import { Routine, Blueprint, Operation } from '@dxos/compute';
+import { Instructions, Operation, Skill } from '@dxos/compute';
 import { Database, Feed, Filter, JsonSchema, Query, Scope, Type, View } from '@dxos/echo';
 
 import { SchemaList } from './definitions';
 
 // TODO(dmaretskyi): This is a balance between not filling the agent's context with too many types and not excluding important types.
-const EXCLUDED_TYPES = [Type.Type, View.View, Routine.Routine, Blueprint.Blueprint, Feed.Feed];
+const EXCLUDED_TYPES = [Type.Type, View.View, Instructions.Instructions, Skill.Skill, Feed.Feed];
 const excludedTypenames = EXCLUDED_TYPES.map((type) => Type.getTypename(type));
 
 export default SchemaList.pipe(