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

package/src/blueprints/agent/index.ts

@@ -1,6 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-export { default as AgentBlueprint } from './blueprint';
-export { AgentBlueprintHandlers, AgentBlueprintOperations } from './operations';

package/src/blueprints/agent/operations/get-context.ts

@@ -1,58 +0,0 @@
-//
-// Copyright 2026 DXOS.org
-//
-
-import * as Effect from 'effect/Effect';
-
-import { AiContext } from '@dxos/assistant';
-import { Operation } from '@dxos/compute';
-import { Database, Obj } from '@dxos/echo';
-
-import { Plan, Agent } from '../../../types';
-import { GetContext } from './definitions';
-
-export default GetContext.pipe(
-  Operation.withHandler(
-    Effect.fnUntraced(function* () {
-      // This runs unconditionally during system-prompt formatting. A delegated sub-agent has no
-      // agent bound to its context, so degrade gracefully for the zero-agent case — but still
-      // surface the "more than one agent" invariant rather than masking every failure.
-      const agents = yield* AiContext.Service.findObjects(Agent.Agent);
-      if (agents.length === 0) {
-        return { id: '', name: '', instructions: 'No agent context.', plan: 'No plan found.', artifacts: [] };
-      }
-      if (agents.length > 1) {
-        return yield* Effect.fail(new Error(`There should be exactly one agent in context. Got: ${agents.length}`));
-      }
-      const agent = agents[0];
-
-      return {
-        id: agent.id,
-        name: agent.name,
-        instructions: yield* agent.instructions.pipe(Database.load).pipe(
-          Effect.map((_) => _.content),
-          Effect.catchTag('EntityNotFoundError', () => Effect.succeed('No instructions found.')),
-        ),
-        plan: yield* (
-          agent.plan?.pipe(Database.load).pipe(
-            Effect.map(Plan.formatPlan),
-            Effect.catchTag('EntityNotFoundError', () => Effect.succeed('No plan found.')),
-          ) ?? Effect.succeed('No plan found.')
-        ),
-        artifacts: yield* Effect.forEach(agent.artifacts, (artifact) =>
-          Effect.gen(function* () {
-            return {
-              name: artifact.name,
-              type: yield* Database.load(artifact.data).pipe(
-                Effect.map(Obj.getTypename),
-                Effect.catchTag('EntityNotFoundError', () => Effect.succeed('Artifact not found.')),
-              ),
-              dxn: artifact.data.uri,
-            };
-          }),
-        ),
-      };
-    }) as any,
-  ),
-  Operation.opaqueHandler,
-);

package/src/blueprints/automation/index.ts

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

package/src/blueprints/blueprint-manager/blueprint.conversations.json

@@ -1 +0,0 @@
-{"conversations":[{"parameters":{"model":"ai.claude.model.claude-opus-4-6","stream":true,"tools":[{"name":"query-blueprints","description":"Queries available blueprints.","inputSchema":{"$id":"/schemas/%7B%7D","anyOf":[{"type":"object"},{"type":"array"}]}},{"name":"enable-blueprints","description":"Enables blueprints in the current conversation by their keys. Only blueprints with agentCanEnable=true can be enabled. Always call [query-blueprints] first to discover available blueprint keys.","inputSchema":{"type":"object","required":["keys"],"properties":{"keys":{"type":"array","items":{"type":"string"},"description":"The keys of the blueprints to enable.","examples":[["org.dxos.blueprint.memory","org.dxos.blueprint.database"]]}},"additionalProperties":false}},{"name":"refresh-blueprints","description":"Updates the blueprints saved to the database with the latest version from the registry. Sometimes blueprints in the database can become outdated. Use this function to pull in the latest versions.","inputSchema":{"$id":"/schemas/%7B%7D","anyOf":[{"type":"object"},{"type":"array"}]}}]},"prompt":{"content":[{"role":"system","content":"You can call blueprint manager tools. When asked to refresh or sync blueprints from the registry,\ncall the refresh blueprints tool once and then stop.\n\n## Blueprints Definitions\n\n<blueprint>\n  You can query available blueprints and enable them in the current conversation.\n  Use [query-blueprints] to refresh the list of available blueprints.\n  Use [refresh-blueprints] to update blueprint objects stored in the database from the built-in registry when they have drifted.\n  Use [enable-blueprints] to enable blueprints by their keys. Always call [query-blueprints] first.\n  Only blueprints with agentCanEnable=true can be enabled by the agent.\n  \n  <available_blueprints>\n  -  \"Database\" -- Query and manipulate objects in the ECHO database. [agent-can-enable]\n  -  \"Discord\" -- Discord integration.\n  -  \"Memory\" -- Persistent memory storage and retrieval. [agent-can-enable]\n  </available_blueprints>\n  \n  NOTE: You must enable the blueprint to use it, only then the tools from that blueprint will appear.\n</blueprint>","options":{}},{"role":"user","content":"Refresh blueprints from the registry so database copies match the built-in definitions.","options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01EnWRrZtYvker1hoFaUftiX","modelId":"claude-opus-4-6","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"reasoning-start","id":"0","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"The user wants to refresh blueprints from the registry. I should call the refresh-blueprints tool.","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"","metadata":{"anthropic":{"type":"thinking","signature":"EqgCCmMIDhgCKkBdz2UkSiBc+mB42bn4XBMulDdlfY744r6A3/CtRIj5ka8kLuAbmGbpsDHh15YA4AXwrTKjmGFVws1/iQVVcX0NMg9jbGF1ZGUtb3B1cy00LTY4AEIIdGhpbmtpbmcSDC1IWXx2nxKJlumiFBoMODifRWw+vJr3M9oxIjCNeGHzgul3HZTZVS1Y1fq36Z6+uk9jVJtfR1kiZDmfUabkraoD+PzSoABC7+HQSl4qc4hegrTArcyY5OVZiDXjw5cbBhF72gChkZu+A5b/wqIxjxdVTqj5Mk3W9dVK7gF5K9ATIOu8KeHLwz9wFEZgmK9vBQhhWrX+X0SaZ7Tds2fllZyPf+1u7EbqQUDP0fp8mjeXRSKJLeTBGTw/d5Ul0Y3/DIgYAQ=="}}},{"type":"reasoning-end","id":"0","metadata":{}},{"type":"text-start","id":"1","metadata":{}},{"type":"text-delta","id":"1","delta":"I","metadata":{}},{"type":"text-delta","id":"1","delta":"'ll refresh the blueprints from the registry now.","metadata":{}},{"type":"text-end","id":"1","metadata":{}},{"type":"tool-params-start","id":"toolu_0191HNbgqXmmaNXfW6keirtd","name":"refresh-blueprints","providerExecuted":false,"metadata":{}},{"type":"tool-params-delta","id":"toolu_0191HNbgqXmmaNXfW6keirtd","delta":"","metadata":{}},{"type":"tool-params-end","id":"toolu_0191HNbgqXmmaNXfW6keirtd","metadata":{}},{"type":"finish","reason":"tool-calls","usage":{"inputTokens":1086,"outputTokens":90,"totalTokens":1176},"metadata":{"anthropic":{"usage":{"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"input_tokens":1086,"output_tokens":40,"server_tool_use":null,"service_tier":"standard"}}}}]},{"parameters":{"model":"ai.claude.model.claude-opus-4-6","stream":true,"tools":[{"name":"query-blueprints","description":"Queries available blueprints.","inputSchema":{"$id":"/schemas/%7B%7D","anyOf":[{"type":"object"},{"type":"array"}]}},{"name":"enable-blueprints","description":"Enables blueprints in the current conversation by their keys. Only blueprints with agentCanEnable=true can be enabled. Always call [query-blueprints] first to discover available blueprint keys.","inputSchema":{"type":"object","required":["keys"],"properties":{"keys":{"type":"array","items":{"type":"string"},"description":"The keys of the blueprints to enable.","examples":[["org.dxos.blueprint.memory","org.dxos.blueprint.database"]]}},"additionalProperties":false}},{"name":"refresh-blueprints","description":"Updates the blueprints saved to the database with the latest version from the registry. Sometimes blueprints in the database can become outdated. Use this function to pull in the latest versions.","inputSchema":{"$id":"/schemas/%7B%7D","anyOf":[{"type":"object"},{"type":"array"}]}}]},"prompt":{"content":[{"role":"system","content":"You can call blueprint manager tools. When asked to refresh or sync blueprints from the registry,\ncall the refresh blueprints tool once and then stop.\n\n## Blueprints Definitions\n\n<blueprint>\n  You can query available blueprints and enable them in the current conversation.\n  Use [query-blueprints] to refresh the list of available blueprints.\n  Use [refresh-blueprints] to update blueprint objects stored in the database from the built-in registry when they have drifted.\n  Use [enable-blueprints] to enable blueprints by their keys. Always call [query-blueprints] first.\n  Only blueprints with agentCanEnable=true can be enabled by the agent.\n  \n  <available_blueprints>\n  -  \"Database\" -- Query and manipulate objects in the ECHO database. [agent-can-enable]\n  -  \"Discord\" -- Discord integration.\n  -  \"Memory\" -- Persistent memory storage and retrieval. [agent-can-enable]\n  </available_blueprints>\n  \n  NOTE: You must enable the blueprint to use it, only then the tools from that blueprint will appear.\n</blueprint>","options":{}},{"role":"user","content":"Refresh blueprints from the registry so database copies match the built-in definitions.","options":{}},{"role":"assistant","content":[{"type":"reasoning","text":"The user wants to refresh blueprints from the registry. I should call the refresh-blueprints tool.","options":{}},{"type":"text","text":"I'll refresh the blueprints from the registry now.","options":{}},{"type":"tool-call","id":"toolu_0191HNbgqXmmaNXfW6keirtd","name":"refresh-blueprints","params":{},"providerExecuted":false,"options":{}}],"options":{}},{"role":"tool","content":[{"type":"tool-result","id":"toolu_0191HNbgqXmmaNXfW6keirtd","name":"refresh-blueprints","isFailure":false,"result":{},"providerExecuted":false,"options":{}}],"options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01UYmSHxnE5L1YWqDDnmQtpE","modelId":"claude-opus-4-6","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"text-start","id":"0","metadata":{}},{"type":"text-delta","id":"0","delta":"The blueprints stored","metadata":{}},{"type":"text-delta","id":"0","delta":" in the database have been updated to match the latest built-in definitions from the registry. Everything should","metadata":{}},{"type":"text-delta","id":"0","delta":" now be in sync.","metadata":{}},{"type":"text-end","id":"0","metadata":{}},{"type":"finish","reason":"stop","usage":{"inputTokens":1149,"outputTokens":33,"totalTokens":1182},"metadata":{"anthropic":{"usage":{"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"input_tokens":1149,"output_tokens":5,"server_tool_use":null,"service_tier":"standard"}}}}]}]}

package/src/blueprints/blueprint-manager/blueprint.test.ts

@@ -1,156 +0,0 @@
-//
-// Copyright 2026 DXOS.org
-//
-
-import { describe, expect, it } from '@effect/vitest';
-import * as Effect from 'effect/Effect';
-import * as Layer from 'effect/Layer';
-
-import { AiContext, AiSession } from '@dxos/assistant';
-import { Blueprint, Operation } from '@dxos/compute';
-import { Obj } from '@dxos/echo';
-import { TestHelpers } from '@dxos/effect/testing';
-import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
-import { EntityId } from '@dxos/keys';
-
-import { DatabaseBlueprint, DiscordBlueprint, MemoryBlueprint } from '../index';
-import { BlueprintManagerHandlers } from './operations';
-import { EnableBlueprints, QueryBlueprints } from './operations/definitions';
-
-EntityId.dangerouslyDisableRandomness();
-
-const TestLayer = AssistantTestLayer({
-  aiServicePreset: 'edge-remote',
-  operationHandlers: BlueprintManagerHandlers,
-  types: [Blueprint.Blueprint],
-  blueprints: [DatabaseBlueprint.make(), MemoryBlueprint.make(), DiscordBlueprint.make()],
-  tracing: 'pretty',
-});
-
-const provideTestLayers = Effect.provide(AiSession.Service.layerNewFeed().pipe(Layer.provideMerge(TestLayer)));
-
-/**
- * Gets the conversation DXN for passing to Operation.invoke options.
- */
-const getConversationDXN = Effect.gen(function* () {
-  const session = yield* AiSession.Service;
-  return Obj.getURI(session.feed);
-});
-
-describe('Blueprint Manager', () => {
-  it.effect(
-    'query-blueprints: returns all registered blueprints',
-    Effect.fnUntraced(
-      function* (_) {
-        const conversation = yield* getConversationDXN;
-        const result = yield* Operation.invoke(QueryBlueprints, {}, { conversation });
-        expect(result).toHaveLength(3);
-        const keys = result.map((blueprint: Blueprint.Blueprint) => Obj.getMeta(blueprint).key);
-        expect(keys).toContain('org.dxos.blueprint.database');
-        expect(keys).toContain('org.dxos.blueprint.memory');
-        expect(keys).toContain('org.dxos.blueprint.discord');
-      },
-      provideTestLayers,
-      TestHelpers.provideTestContext,
-    ),
-    { timeout: 30_000 },
-  );
-
-  it.effect(
-    'enable-blueprints: enables blueprints with agentCanEnable=true',
-    Effect.fnUntraced(
-      function* (_) {
-        const conversation = yield* getConversationDXN;
-        const { enabled, rejected } = yield* Operation.invoke(
-          EnableBlueprints,
-          { keys: ['org.dxos.blueprint.database'] },
-          { conversation },
-        );
-        expect(enabled).toHaveLength(1);
-        expect(Obj.getMeta(enabled[0]).key).toBe('org.dxos.blueprint.database');
-        expect(rejected).toHaveLength(0);
-
-        const { binder } = yield* AiContext.Service;
-        const bound = binder.getBlueprints();
-        expect(bound.some((bp: Blueprint.Blueprint) => Obj.getMeta(bp).key === 'org.dxos.blueprint.database')).toBe(
-          true,
-        );
-      },
-      provideTestLayers,
-      TestHelpers.provideTestContext,
-    ),
-    { timeout: 30_000 },
-  );
-
-  it.effect(
-    'enable-blueprints: rejects blueprints without agentCanEnable',
-    Effect.fnUntraced(
-      function* (_) {
-        const conversation = yield* getConversationDXN;
-        const { enabled, rejected } = yield* Operation.invoke(
-          EnableBlueprints,
-          { keys: ['org.dxos.blueprint.discord'] },
-          { conversation },
-        );
-        expect(enabled).toHaveLength(0);
-        expect(rejected).toHaveLength(1);
-        expect(rejected[0].key).toBe('org.dxos.blueprint.discord');
-
-        const { binder } = yield* AiContext.Service;
-        const bound = binder.getBlueprints();
-        expect(bound.some((bp: Blueprint.Blueprint) => Obj.getMeta(bp).key === 'org.dxos.blueprint.discord')).toBe(
-          false,
-        );
-      },
-      provideTestLayers,
-      TestHelpers.provideTestContext,
-    ),
-    { timeout: 30_000 },
-  );
-
-  it.effect(
-    'enable-blueprints: mixed keys enables only allowed ones',
-    Effect.fnUntraced(
-      function* (_) {
-        const conversation = yield* getConversationDXN;
-        const { enabled, rejected } = yield* Operation.invoke(
-          EnableBlueprints,
-          {
-            keys: ['org.dxos.blueprint.database', 'org.dxos.blueprint.memory', 'org.dxos.blueprint.discord'],
-          },
-          { conversation },
-        );
-        expect(enabled).toHaveLength(2);
-        const enabledKeys = enabled.map((bp: Blueprint.Blueprint) => Obj.getMeta(bp).key);
-        expect(enabledKeys).toContain('org.dxos.blueprint.database');
-        expect(enabledKeys).toContain('org.dxos.blueprint.memory');
-        expect(rejected).toHaveLength(1);
-        expect(rejected[0].key).toBe('org.dxos.blueprint.discord');
-      },
-      provideTestLayers,
-      TestHelpers.provideTestContext,
-    ),
-    { timeout: 30_000 },
-  );
-
-  it.effect(
-    'enable-blueprints: unknown keys are rejected with reason',
-    Effect.fnUntraced(
-      function* (_) {
-        const conversation = yield* getConversationDXN;
-        const { enabled, rejected } = yield* Operation.invoke(
-          EnableBlueprints,
-          { keys: ['org.dxos.blueprint.nonexistent'] },
-          { conversation },
-        );
-        expect(enabled).toHaveLength(0);
-        expect(rejected).toHaveLength(1);
-        expect(rejected[0].key).toBe('org.dxos.blueprint.nonexistent');
-        expect(rejected[0].reason).toContain('not found');
-      },
-      provideTestLayers,
-      TestHelpers.provideTestContext,
-    ),
-    { timeout: 30_000 },
-  );
-});

package/src/blueprints/blueprint-manager/blueprint.ts

@@ -1,49 +0,0 @@
-//
-// Copyright 2026 DXOS.org
-//
-
-import { Blueprint, Template } from '@dxos/compute';
-import { DXN } from '@dxos/keys';
-import { trim } from '@dxos/util';
-
-import { EnableBlueprints, QueryBlueprints } from './operations/definitions';
-
-const BLUEPRINT_KEY = 'org.dxos.blueprint.blueprintManager';
-
-const make = () =>
-  Blueprint.make({
-    key: BLUEPRINT_KEY,
-    name: 'Blueprint Manager',
-    description: 'Query and enable blueprints in the current conversation.',
-    instructions: Template.make({
-      source: trim`
-        You can query available blueprints and enable them in the current conversation.
-        Use [query-blueprints] to refresh the list of available blueprints.
-        Use [enable-blueprints] to enable blueprints by their keys. Always call [query-blueprints] first.
-        Only blueprints with agentCanEnable=true can be enabled by the agent.
-
-        <available_blueprints>
-        {{#each blueprints}}
-        - {{key}} "{{name}}"{{#if description}} -- {{description}}{{/if}}{{#if agentCanEnable}} [agent-can-enable]{{/if}}
-        {{/each}}
-        </available_blueprints>
-
-        NOTE: You must enable the blueprint to use it, only then the tools from that blueprint will appear.
-      `,
-      inputs: [
-        {
-          name: 'blueprints',
-          kind: 'operation',
-          operation: DXN.getName(QueryBlueprints.meta.key),
-        },
-      ],
-    }),
-    tools: Blueprint.toolDefinitions({ operations: [QueryBlueprints, EnableBlueprints] }),
-  });
-
-const blueprint: Blueprint.Definition = {
-  key: BLUEPRINT_KEY,
-  make,
-};
-
-export default blueprint;

package/src/blueprints/blueprint-manager/index.ts

@@ -1,6 +0,0 @@
-//
-// Copyright 2026 DXOS.org
-//
-
-export { default as BlueprintManagerBlueprint } from './blueprint';
-export { BlueprintManagerHandlers, BlueprintManagerOperations } from './operations';

package/src/blueprints/blueprint-manager/operations/definitions.ts

@@ -1,48 +0,0 @@
-//
-// Copyright 2026 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-
-import { AiContext } from '@dxos/assistant';
-import { Blueprint, Operation } from '@dxos/compute';
-import { Database, Registry, Type } from '@dxos/echo';
-import { DXN } from '@dxos/keys';
-
-export const QueryBlueprints = Operation.make({
-  meta: {
-    key: DXN.make('org.dxos.function.blueprintManager.queryBlueprints'),
-    name: 'Query blueprints',
-    description: 'Queries available blueprints.',
-    icon: 'ph--blueprint--regular',
-  },
-  input: Schema.Struct({}),
-  output: Schema.Array(Type.getSchema(Blueprint.Blueprint)),
-  services: [Registry.Service],
-});
-
-export const EnableBlueprints = Operation.make({
-  meta: {
-    key: DXN.make('org.dxos.function.blueprintManager.enableBlueprints'),
-    name: 'Enable blueprints',
-    description:
-      'Enables blueprints in the current conversation by their keys. Only blueprints with agentCanEnable=true can be enabled. Always call [query-blueprints] first to discover available blueprint keys.',
-    icon: 'ph--plugs-connected--regular',
-  },
-  input: Schema.Struct({
-    keys: Schema.Array(Schema.String).annotations({
-      description: 'The keys of the blueprints to enable.',
-      examples: [['org.dxos.blueprint.memory', 'org.dxos.blueprint.database']],
-    }),
-  }),
-  output: Schema.Struct({
-    enabled: Schema.Array(Type.getSchema(Blueprint.Blueprint)),
-    rejected: Schema.Array(
-      Schema.Struct({
-        key: Schema.String,
-        reason: Schema.String,
-      }),
-    ),
-  }),
-  services: [Registry.Service, Database.Service, AiContext.Service],
-});

package/src/blueprints/blueprint-manager/operations/enable-blueprints.ts

@@ -1,46 +0,0 @@
-//
-// Copyright 2026 DXOS.org
-//
-
-import * as Effect from 'effect/Effect';
-import * as Either from 'effect/Either';
-
-import { AiContext } from '@dxos/assistant';
-import { Blueprint, Operation } from '@dxos/compute';
-import { Ref } from '@dxos/echo';
-
-import { EnableBlueprints } from './definitions';
-
-export default EnableBlueprints.pipe(
-  Operation.withHandler(
-    Effect.fnUntraced(function* ({ keys }) {
-      const enabled: Blueprint.Blueprint[] = [];
-      const rejected: { key: string; reason: string }[] = [];
-
-      for (const key of keys) {
-        const result = yield* Blueprint.resolve(key).pipe(
-          Effect.mapError(() => ({ key, reason: 'Blueprint not found in registry.' })),
-          Effect.either,
-        );
-        if (Either.isLeft(result)) {
-          rejected.push(result.left);
-          continue;
-        }
-        if (!result.right.agentCanEnable) {
-          rejected.push({ key, reason: 'Blueprint does not allow agent auto-enable (agentCanEnable is not set).' });
-          continue;
-        }
-        const dbBlueprint = yield* Blueprint.upsert(key).pipe(Effect.orDie);
-        enabled.push(dbBlueprint);
-      }
-
-      if (enabled.length > 0) {
-        yield* AiContext.Service.bindContext({
-          blueprints: enabled.map(Ref.make),
-        });
-      }
-
-      return { enabled, rejected };
-    }),
-  ),
-);

package/src/blueprints/blueprint-manager/operations/index.ts

@@ -1,12 +0,0 @@
-//
-// Copyright 2026 DXOS.org
-//
-
-import { OperationHandlerSet } from '@dxos/compute';
-
-export * as BlueprintManagerOperations from './definitions';
-
-export const BlueprintManagerHandlers = OperationHandlerSet.lazy(
-  () => import('./query-blueprints'),
-  () => import('./enable-blueprints'),
-);

package/src/blueprints/blueprint-manager/operations/query-blueprints.ts

@@ -1,19 +0,0 @@
-//
-// Copyright 2026 DXOS.org
-//
-
-import * as Effect from 'effect/Effect';
-
-import { Blueprint, Operation } from '@dxos/compute';
-import { Filter, Registry } from '@dxos/echo';
-
-import { QueryBlueprints } from './definitions';
-
-export default QueryBlueprints.pipe(
-  Operation.withHandler(
-    Effect.fnUntraced(function* () {
-      const blueprints = yield* Registry.runQuery(Filter.type(Blueprint.Blueprint));
-      return blueprints.slice().sort(({ name: a }, { name: b }) => a.localeCompare(b));
-    }),
-  ),
-);