@dxos/assistant-toolkit 0.8.4-main.e8ec1fe → 0.8.4-main.fcfe5033a5

package/src/blueprints/database/index.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { default as DatabaseBlueprint } from './blueprint';
+export {
+  Query as DatabaseQuery,
+  Load as DatabaseLoad,
+  ObjectCreate,
+  ObjectUpdate,
+  ObjectDelete,
+  SchemaAdd,
+  SchemaList,
+  ContextAdd,
+  ContextRemove,
+  RelationCreate,
+  RelationDelete,
+  TagAdd,
+  TagRemove,
+  DatabaseHandlers,
+} from './functions';

package/src/blueprints/design/blueprint.test.ts

@@ -0,0 +1,77 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { AgentService } from '@dxos/assistant';
+import { AssistantTestLayer } from '@dxos/assistant/testing';
+import { Blueprint } from '@dxos/blueprints';
+import { Database, Obj } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { log } from '@dxos/log';
+import { Markdown } from '@dxos/plugin-markdown/types';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+import { MarkdownHandlers } from '../markdown';
+import DesignBlueprint from './blueprint';
+
+const TestLayer = AssistantTestLayer({
+  operationHandlers: MarkdownHandlers,
+  types: [Text.Text, Markdown.Document, Blueprint.Blueprint],
+  blueprints: [DesignBlueprint.make()],
+});
+
+describe('Design Blueprint', { timeout: 120_000 }, () => {
+  it.scoped(
+    'design blueprint',
+    Effect.fn(
+      function* ({ expect }) {
+        const agent = yield* AgentService.createSession({
+          blueprints: [DesignBlueprint.make()],
+        });
+
+        const artifact = yield* Database.add(Markdown.make({ content: 'Hello, world!' }));
+        let prevContent = artifact.content;
+
+        {
+          const prompt = trim`
+            I want to design a new feature for our product.
+
+            We need to add a user profile system with the following requirements:
+            1. Users should be able to create and edit their profiles
+            2. Profile should include basic info like name, bio, avatar
+            3. Users can control privacy settings for their profile
+            4. Profile should show user's activity history
+            5. Need to consider data storage and security implications
+
+            Let's capture the key design decisions in our spec in ${Obj.getDXN(artifact)}
+          `;
+
+          yield* agent.submitPrompt(prompt);
+          yield* agent.waitForCompletion();
+          log.info('spec', { doc: artifact });
+          expect(artifact.content).not.toBe(prevContent);
+          prevContent = artifact.content;
+        }
+
+        {
+          const prompt = trim`
+            I want this to be built on top of Durable Objects and SQLite database.
+            Adjust the spec to reflect this.
+          `;
+
+          yield* agent.submitPrompt(prompt);
+          yield* agent.waitForCompletion();
+          expect(artifact.content).not.toBe(prevContent);
+          prevContent = artifact.content;
+        }
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+      TestHelpers.taggedTest('llm'),
+    ),
+  );
+});

package/src/blueprints/design/{design-blueprint.ts → blueprint.ts}

@@ -2,13 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import { ToolId } from '@dxos/ai';
+import { type AppCapabilities } from '@dxos/app-toolkit';
 import { Blueprint } from '@dxos/blueprints';
-import { Obj, Ref } from '@dxos/echo';
+import { Ref } from '@dxos/echo';
 import { Text } from '@dxos/schema';
 import { trim } from '@dxos/util';
 
-import { Document } from '../../functions';
+import { MarkdownCreate, MarkdownRead, MarkdownUpdate } from '../markdown';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.design';
 
 const instructions = trim`
   You manage a design spec based on the conversation.
@@ -20,14 +22,20 @@ const instructions = trim`
   Do not announce when you read or write the design spec document.
 `;
 
-const blueprint: Blueprint.Blueprint = Obj.make(Blueprint.Blueprint, {
-  key: 'dxos.org/blueprint/design',
-  name: 'Design Spec',
-  description: 'Preserve the conversation in the design spec.',
-  instructions: {
-    source: Ref.make(Text.make(instructions)),
-  },
-  tools: [Document.read, Document.update].map((fn) => ToolId.make(fn.key)),
-});
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Design Spec',
+    description: 'Preserve the conversation in the design spec.',
+    instructions: {
+      source: Ref.make(Text.make(instructions)),
+    },
+    tools: Blueprint.toolDefinitions({ operations: [MarkdownCreate, MarkdownRead, MarkdownUpdate] }),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  make,
+};
 
 export default blueprint;

package/src/blueprints/design/index.ts

@@ -2,6 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-import blueprint from './design-blueprint';
-
-export default blueprint;
+export { default as DesignBlueprint } from './blueprint';

package/src/blueprints/discord/blueprint.ts

@@ -0,0 +1,42 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint } from '@dxos/blueprints';
+import { Ref } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+import { FetchMessages } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.discord';
+
+/**
+ * Agent prompt instructions for managing hierarchical task lists.
+ */
+const instructions = trim`
+  You are able to fetch messages from Discord servers.
+
+  Known servers:
+
+  DXOS serverId: 837138313172353095
+`;
+
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Discord',
+    description: 'Discord integration.',
+    instructions: {
+      source: Ref.make(Text.make(instructions)),
+    },
+    tools: Blueprint.toolDefinitions({ operations: [FetchMessages] }),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  make,
+};
+
+export default blueprint;

package/src/blueprints/discord/functions/definitions.ts

@@ -0,0 +1,71 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { CredentialsService, Trace } from '@dxos/functions';
+import { Operation } from '@dxos/operation';
+
+// TODO(dmaretskyi): Extract.
+const TimeRangeSchema = Schema.String.pipe(Schema.pattern(/\d+(s|m|h|d)/)).annotations({
+  description: 'Time range. 1d - 1 day, 2h - 2 hours, 30m - 30 minutes, 15s - 15 seconds.',
+  examples: ['1d', '2h', '30m', '15s'],
+});
+
+export const TimeRange = Object.assign(TimeRangeSchema, {
+  toSeconds(timeRange: string) {
+    const match = timeRange.match(/(\d+)(s|m|h|d)/);
+    if (!match) {
+      throw new Error(`Invalid time range: ${timeRange}`);
+    }
+    const [_, amount, unit] = match;
+    switch (unit) {
+      case 's':
+        return Number(amount);
+      case 'm':
+        return Number(amount) * 60;
+      case 'h':
+        return Number(amount) * 60 * 60;
+      case 'd':
+        return Number(amount) * 24 * 60 * 60;
+      default:
+        throw new Error(`Invalid time range unit: ${unit}`);
+    }
+  },
+});
+
+export const FetchMessages = Operation.make({
+  meta: {
+    key: 'org.dxos.function.fetch-discord-messages',
+    name: 'Sync Discord messages',
+  },
+  input: Schema.Struct({
+    serverId: Schema.String.annotations({
+      description: 'The ID of the server to fetch messages from.',
+    }),
+    channelId: Schema.optional(Schema.String).annotations({
+      description:
+        'The ID of the channel to fetch messages from. Will crawl all channels from the server if not specified.',
+    }),
+    after: Schema.optional(Schema.Number).annotations({
+      description:
+        'Fetch messages that were sent after a given date. Unix timestamp in seconds. Exclusive with `last`.',
+    }),
+    last: TimeRange.annotations({
+      description:
+        'Time range to fetch most recent messages. Specifies the range in the past, from now. "1d" would fetch messages from the last 24 hours.',
+    }),
+    limit: Schema.optional(Schema.Number).annotations({
+      description: 'The maximum number of messages to fetch.',
+    }),
+    pageSize: Schema.optional(Schema.Number).annotations({
+      description: 'The number of messages to fetch per page.',
+    }),
+    ignoreUsernames: Schema.optional(Schema.Array(Schema.String)).annotations({
+      description: 'Exclude messages from these usernames.',
+    }),
+  }),
+  output: Schema.Any,
+  services: [CredentialsService, Trace.TraceService],
+});

package/src/blueprints/discord/functions/fetch-messages.test.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as FetchHttpClient from '@effect/platform/FetchHttpClient';
+import { describe, it } from '@effect/vitest';
+import * as Config from 'effect/Config';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { AssistantTestLayer } from '@dxos/assistant/testing';
+import { TestHelpers } from '@dxos/effect/testing';
+import { CredentialsService } from '@dxos/functions';
+import { Operation, OperationHandlerSet } from '@dxos/operation';
+
+import { default as fetchMessages } from './fetch-messages';
+
+const TestLayer = AssistantTestLayer({
+  operationHandlers: OperationHandlerSet.make(fetchMessages),
+});
+
+const TestLayerWithCredentials = Layer.mergeAll(
+  CredentialsService.layerConfig([{ service: 'discord.com', apiKey: Config.redacted('DISCORD_TOKEN') }]),
+  FetchHttpClient.layer,
+).pipe(Layer.provideMerge(TestLayer));
+
+const DXOS_SERVER_ID = '837138313172353095';
+
+describe('Feed', { timeout: 600_000 }, () => {
+  it.effect(
+    'fetch discord messages',
+    Effect.fnUntraced(
+      function* (_) {
+        const messages = yield* Operation.invoke(fetchMessages, {
+          serverId: DXOS_SERVER_ID,
+          last: '7d',
+        }).pipe(Effect.orDie);
+        console.log(messages);
+      },
+      Effect.provide(TestLayerWithCredentials),
+      TestHelpers.provideTestContext,
+      TestHelpers.taggedTest('sync'),
+    ),
+  );
+});

package/src/blueprints/discord/functions/fetch-messages.ts

@@ -0,0 +1,199 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as FetchHttpClient from '@effect/platform/FetchHttpClient';
+import { DiscordConfig, DiscordREST, DiscordRESTMemoryLive } from 'dfx';
+import type {
+  GuildChannelResponse,
+  MessageResponse,
+  PrivateChannelResponse,
+  PrivateGroupChannelResponse,
+  ThreadResponse,
+} from 'dfx/types';
+import * as Array from 'effect/Array';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+
+import { Obj } from '@dxos/echo';
+import { CredentialsService, Trace } from '@dxos/functions';
+import { log } from '@dxos/log';
+import { Operation } from '@dxos/operation';
+import { Message } from '@dxos/types';
+
+import { FetchMessages, TimeRange } from './definitions';
+
+const DiscordConfigFromCredential = Layer.unwrapEffect(
+  Effect.gen(function* () {
+    return DiscordConfig.layer({
+      token: yield* CredentialsService.getApiKey({ service: 'discord.com' }),
+      rest: {
+        baseUrl: 'https://api-proxy.dxos.workers.dev/discord.com/api/v10',
+      },
+    });
+  }),
+);
+
+type DiscordChannel = GuildChannelResponse | PrivateChannelResponse | PrivateGroupChannelResponse | ThreadResponse;
+
+const DEFAULT_AFTER = 1704067200; // 2024-01-01
+const DEFAULT_LIMIT = 500;
+const DEFAULT_IGNORE_USERNAMES = ['GitHub', 'Needle'];
+
+// TODO(dmaretskyi): Align with standard thread type.
+type Thread = {
+  discordChannelId: string;
+  name?: string;
+  messages: Message.Message[];
+};
+
+export default FetchMessages.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(
+      function* ({
+        serverId,
+        channelId,
+        after,
+        last,
+        pageSize = 100,
+        limit = DEFAULT_LIMIT,
+        ignoreUsernames = DEFAULT_IGNORE_USERNAMES,
+      }) {
+        if (!after && !last) {
+          throw new Error('cannot specify both `after` and `last`');
+        }
+        const afterTs = last ? Date.now() / 1000 - TimeRange.toSeconds(last) : (after ?? DEFAULT_AFTER);
+
+        const rest = yield* DiscordREST;
+
+        let channels: DiscordChannel[] = [];
+        channels.push(...(yield* rest.listGuildChannels(serverId)));
+        const { threads: guildThreads } = yield* rest.getActiveGuildThreads(serverId);
+        channels.push(...guildThreads);
+        if (channelId) {
+          channels = channels.filter((channel) => channel.id === channelId);
+        }
+        if (channels.length === 0) {
+          throw new Error('no channels found');
+        }
+        for (const channel of channels) {
+          log.info('channel', { id: channel.id, name: 'name' in channel ? channel.name : undefined });
+        }
+
+        yield* Trace.emitStatus(`Will fetch from channels: ${channels.length}`);
+
+        const threads = yield* Effect.forEach(
+          channels,
+          Effect.fnUntraced(function* (channel) {
+            const allMessages: Message.Message[] = [];
+
+            let lastMessage: Option.Option<Message.Message> = Option.none();
+            while (true) {
+              const { id: lastId = undefined } = Function.pipe(
+                lastMessage,
+                Option.map(Obj.getKeys('discord.com')),
+                Option.flatMap(Option.fromIterable),
+                Option.getOrElse(() => ({ id: undefined })),
+              );
+
+              const options = {
+                after: !lastId ? `${generateSnowflake(afterTs)}` : lastId,
+                limit: pageSize,
+              };
+              log.info('fetching messages', {
+                lastId,
+                afterTs,
+                afterSnowflake: options.after,
+                after: parseSnowflake(options.after),
+                limit: options.limit,
+              });
+              const messages = yield* rest.listMessages(channel.id, options).pipe(
+                Effect.map(Array.map(makeMessage)),
+                Effect.map(Array.reverse),
+                Effect.catchTag('ErrorResponse', (err) =>
+                  err.cause.code === 50001 ? Effect.succeed([]) : Effect.fail(err),
+                ),
+              );
+              if (messages.length > 0) {
+                lastMessage = Option.fromNullable(messages.at(-1));
+                allMessages.push(...messages);
+              } else {
+                break;
+              }
+              yield* Trace.emitStatus(`Fetched messages: ${allMessages.length}`);
+              if (allMessages.length >= limit) {
+                break;
+              }
+            }
+
+            return {
+              discordChannelId: channel.id,
+              name: 'name' in channel ? (channel.name ?? undefined) : undefined,
+              messages: allMessages
+                .filter((message) => !message.sender.name || !ignoreUsernames.includes(message.sender.name))
+                .filter((message) =>
+                  message.blocks.some((block: any) => block._tag === 'text' && block.text.trim().length > 0),
+                ),
+            } satisfies Thread;
+          }),
+          { concurrency: 10 },
+        );
+
+        return threads
+          .filter((thread) => thread.messages.length > 0)
+          .map(serializeThread)
+          .join('\n');
+      },
+      Effect.provide(
+        DiscordRESTMemoryLive.pipe(Layer.provideMerge(DiscordConfigFromCredential)).pipe(
+          Layer.provide(FetchHttpClient.layer),
+        ),
+      ),
+      Effect.orDie,
+    ),
+  ),
+);
+
+/**
+ * @param unixTimestamp in seconds
+ */
+const generateSnowflake = (unixTimestamp: number): bigint => {
+  const discordEpoch = 1420070400000n; // Discord Epoch (ms)
+  return (BigInt(unixTimestamp * 1000) - discordEpoch) << 22n;
+};
+
+const parseSnowflake = (snowflake: string): Date => {
+  const discordEpoch = 1420070400000n; // Discord Epoch (ms)
+  return new Date(Number((BigInt(snowflake) >> 22n) + discordEpoch));
+};
+
+// TODO(burdon): Move to @dxos/types.
+const makeMessage = (message: MessageResponse): Message.Message =>
+  Obj.make(Message.Message, {
+    [Obj.Meta]: {
+      keys: [
+        { id: message.id, source: 'discord.com' },
+        { id: message.channel_id, source: 'discord.com/thread' },
+      ],
+    },
+    sender: { name: message.author.username },
+    created: message.timestamp,
+    blocks: [{ _tag: 'text', text: message.content }],
+  });
+
+/**
+ * Standard JSON serialization is to verbose for large amounts of data.
+ */
+const serializeThread = (thread: Thread): string => {
+  return `<thread id=${thread.discordChannelId} name=${thread.name ?? ''}>\n${thread.messages
+    .map(
+      (message) =>
+        `  ${message.sender.name}: ${message.blocks
+          .filter((block: any) => block._tag === 'text')
+          .map((block: any) => block.text)
+          .join(' ')}`,
+    )
+    .join('\n')}\n</thread>`;
+};

package/src/blueprints/discord/functions/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/operation';
+
+export * from './definitions';
+
+export const DiscordHandlers = OperationHandlerSet.lazy(() => import('./fetch-messages'));

package/src/blueprints/discord/index.ts

@@ -2,6 +2,5 @@
 // Copyright 2025 DXOS.org
 //
 
-import blueprint from './discord-blueprint';
-
-export default blueprint;
+export { default as DiscordBlueprint } from './blueprint';
+export { FetchMessages, DiscordHandlers } from './functions';

package/src/blueprints/github/functions/definitions.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as HttpClient from '@effect/platform/HttpClient';
+import * as Schema from 'effect/Schema';
+
+import { CredentialsService } from '@dxos/functions';
+import { Operation } from '@dxos/operation';
+
+export const FetchPrs = Operation.make({
+  meta: {
+    key: 'org.dxos.function.github.fetch-prs',
+    name: 'Fetch PRs',
+    description: 'Fetches PRs from GitHub.',
+  },
+  input: Schema.Struct({
+    owner: Schema.String.annotations({
+      description: 'GitHub owner.',
+    }),
+    repo: Schema.String.annotations({
+      description: 'GitHub repository.',
+    }),
+  }),
+  output: Schema.Any,
+  services: [CredentialsService, HttpClient.HttpClient],
+});

package/src/blueprints/github/functions/fetch-prs.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as HttpClient from '@effect/platform/HttpClient';
+import * as Effect from 'effect/Effect';
+
+import { CredentialsService, withAuthorization } from '@dxos/functions';
+import { Operation } from '@dxos/operation';
+
+import { FetchPrs } from './definitions';
+
+export default FetchPrs.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ owner, repo }) {
+      const credential = yield* CredentialsService.getCredential({ service: 'github.com' });
+      const client = yield* HttpClient.HttpClient.pipe(Effect.map(withAuthorization(credential.apiKey!)));
+
+      const response = yield* client.get(`https://api.github.com/repos/${owner}/${repo}/pulls`);
+      const json: any = yield* response.json;
+      return json;
+    }),
+  ),
+);

package/src/blueprints/github/functions/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/operation';
+
+export * from './definitions';
+
+export const GithubHandlers = OperationHandlerSet.lazy(() => import('./fetch-prs'));

package/src/blueprints/github/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { FetchPrs, GithubHandlers } from './functions';

package/src/blueprints/index.ts

@@ -2,9 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-export { default as DesignBlueprint } from './design';
-export { default as DiscordBlueprint } from './discord';
-export { default as LinearBlueprint } from './linear';
-export { default as PlanningBlueprint } from './planning';
-export { default as ResearchBlueprint } from './research';
-export { default as WebSearchBlueprint, WebSearchToolkit } from './websearch';
+export * from './design';
+export * from './discord';
+export * from './project';
+export * from './linear';
+export * from './markdown';
+export * from './planning';
+export * from './research';
+export * from './websearch';
+export * from './browser';
+export * from './database';
+export * from './memory';
+export * from './automation';
+export * from './blueprint-manager';
+export * from './project-wizard';

package/src/blueprints/linear/blueprint.ts

@@ -0,0 +1,43 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint } from '@dxos/blueprints';
+import { Ref } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+import { SyncIssues } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.linear';
+
+/**
+ * Agent prompt instructions for managing hierarchical task lists.
+ */
+const instructions = trim`
+  You are able to sync Linear workspaces.
+  Sometimes sync does not complete in one go and you need to call the function again.
+
+  Known workspaces:
+
+  DXOS teamId: 1127c63a-6f77-4725-9229-50f6cd47321c
+`;
+
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Linear',
+    description: 'Syncs Linear workspaces.',
+    instructions: {
+      source: Ref.make(Text.make(instructions)),
+    },
+    tools: Blueprint.toolDefinitions({ operations: [SyncIssues] }),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  make,
+};
+
+export default blueprint;