@axium/ai 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/LICENSE.md +157 -0
  2. package/README.md +2 -2
  3. package/db.json +114 -0
  4. package/dist/client/cli.d.ts +1 -0
  5. package/dist/client/cli.js +224 -0
  6. package/dist/client/config.d.ts +196 -0
  7. package/dist/client/config.js +55 -0
  8. package/dist/client/hooks.d.ts +3 -0
  9. package/dist/client/hooks.js +32 -0
  10. package/dist/client/local.d.ts +17 -0
  11. package/dist/client/local.js +112 -0
  12. package/dist/common.d.ts +1318 -0
  13. package/dist/common.js +569 -0
  14. package/dist/hooks.d.ts +13 -0
  15. package/dist/hooks.js +34 -0
  16. package/dist/hub.d.ts +4 -0
  17. package/dist/hub.js +75 -0
  18. package/dist/index.d.ts +1 -0
  19. package/dist/index.js +1 -0
  20. package/dist/integrations/notes.d.ts +1 -0
  21. package/dist/integrations/notes.js +104 -0
  22. package/dist/integrations/tasks.d.ts +1 -0
  23. package/dist/integrations/tasks.js +157 -0
  24. package/dist/loop.d.ts +75 -0
  25. package/dist/loop.js +239 -0
  26. package/dist/memory.d.ts +107 -0
  27. package/dist/memory.js +193 -0
  28. package/dist/node/chat.d.ts +50 -0
  29. package/dist/node/chat.js +60 -0
  30. package/dist/node/llama.d.ts +115 -0
  31. package/dist/node/llama.js +385 -0
  32. package/dist/node/markdown.d.ts +6 -0
  33. package/dist/node/markdown.js +285 -0
  34. package/dist/node/models.d.ts +34 -0
  35. package/dist/node/models.js +287 -0
  36. package/dist/node/web.d.ts +1 -0
  37. package/dist/node/web.js +203 -0
  38. package/dist/server/api/conversations.d.ts +1 -0
  39. package/dist/server/api/conversations.js +216 -0
  40. package/dist/server/api/gateway.d.ts +1 -0
  41. package/dist/server/api/gateway.js +113 -0
  42. package/dist/server/api/memories.d.ts +1 -0
  43. package/dist/server/api/memories.js +129 -0
  44. package/dist/server/api/models.d.ts +1 -0
  45. package/dist/server/api/models.js +161 -0
  46. package/dist/server/api/temporary.d.ts +1 -0
  47. package/dist/server/api/temporary.js +50 -0
  48. package/dist/server/api/timers.d.ts +1 -0
  49. package/dist/server/api/timers.js +27 -0
  50. package/dist/server/api/voice.d.ts +1 -0
  51. package/dist/server/api/voice.js +188 -0
  52. package/dist/server/generation.d.ts +38 -0
  53. package/dist/server/generation.js +299 -0
  54. package/dist/server/memory.d.ts +7 -0
  55. package/dist/server/memory.js +218 -0
  56. package/dist/server/models.d.ts +13 -0
  57. package/dist/server/models.js +59 -0
  58. package/dist/server/preferences.d.ts +3 -0
  59. package/dist/server/preferences.js +12 -0
  60. package/dist/server/timers.d.ts +7 -0
  61. package/dist/server/timers.js +66 -0
  62. package/dist/speech.d.ts +17 -0
  63. package/dist/speech.js +69 -0
  64. package/dist/timers.d.ts +1 -0
  65. package/dist/timers.js +67 -0
  66. package/dist/tools.d.ts +70 -0
  67. package/dist/tools.js +84 -0
  68. package/lib/ChatMessage.svelte +331 -0
  69. package/lib/Composer.svelte +234 -0
  70. package/lib/Conversation.svelte +433 -0
  71. package/lib/ConversationMenu.svelte +18 -0
  72. package/lib/ModelActions.svelte +71 -0
  73. package/lib/ModelOptions.svelte +101 -0
  74. package/lib/ModelStatus.svelte +49 -0
  75. package/lib/ToolCall.svelte +171 -0
  76. package/lib/VoiceMode.svelte +113 -0
  77. package/lib/actions.ts +21 -0
  78. package/lib/index.ts +7 -0
  79. package/lib/live.svelte.ts +113 -0
  80. package/lib/markdown.ts +40 -0
  81. package/lib/preferences.ts +13 -0
  82. package/lib/transition.ts +24 -0
  83. package/lib/tsconfig.json +14 -0
  84. package/lib/voice.svelte.ts +476 -0
  85. package/locales/en.json +316 -0
  86. package/package.json +139 -5
  87. package/routes/ai/+layout.svelte +177 -0
  88. package/routes/ai/+layout.ts +26 -0
  89. package/routes/ai/+page.svelte +109 -0
  90. package/routes/ai/TimerAlerts.svelte +51 -0
  91. package/routes/ai/Timers.svelte +121 -0
  92. package/routes/ai/[id]/+page.svelte +18 -0
  93. package/routes/ai/[id]/+page.ts +14 -0
  94. package/routes/ai/memory/+page.svelte +313 -0
  95. package/routes/ai/memory/+page.ts +10 -0
  96. package/routes/ai/memory/MemoryForm.svelte +111 -0
  97. package/routes/ai/models/+page.svelte +199 -0
  98. package/routes/ai/models/+page.ts +5 -0
  99. package/routes/ai/models/AddModel.svelte +240 -0
  100. package/routes/ai/models/MemoryMeter.svelte +120 -0
  101. package/routes/ai/models/Roles.svelte +159 -0
  102. package/routes/ai/models/[id]/+page.svelte +331 -0
  103. package/routes/ai/models/[id]/+page.ts +6 -0
  104. package/routes/ai/timers.svelte.ts +94 -0
  105. package/routes/tsconfig.json +14 -0
package/dist/hub.js ADDED
@@ -0,0 +1,75 @@
1
+ const hubURL = 'https://huggingface.co/';
2
+ /** @param token A Hugging Face access token, for gated or private repositories */
3
+ async function hubFetch(path, token) {
4
+ const response = await fetch(new URL(path, hubURL), {
5
+ headers: token ? { Authorization: 'Bearer ' + token } : {},
6
+ signal: AbortSignal.timeout(15_000),
7
+ });
8
+ if (!response.ok)
9
+ throw new Error(`Hugging Face: ${response.status} ${response.statusText}`);
10
+ return (await response.json());
11
+ }
12
+ export async function search(query, token) {
13
+ const params = new URLSearchParams({ search: query, filter: 'gguf', sort: 'downloads', direction: '-1', limit: '30' });
14
+ for (const field of ['downloads', 'likes', 'lastModified'])
15
+ params.append('expand[]', field);
16
+ const results = await hubFetch('api/models?' + params.toString(), token);
17
+ return results.map(result => ({
18
+ id: result.id,
19
+ downloads: result.downloads ?? 0,
20
+ likes: result.likes ?? 0,
21
+ modified: result.lastModified ? new Date(result.lastModified) : undefined,
22
+ }));
23
+ }
24
+ const sidecarNames = ['mmproj', 'mtp', 'dflash', 'eagle3', 'dspark'];
25
+ /** The quantization tag llama.cpp reads from a GGUF file name, and the name shared by the shards of a split file */
26
+ function parseFileName(path) {
27
+ const prefix = path.slice(0, -'.gguf'.length).replace(/-\d{5}-of-\d{5}$/i, '');
28
+ const tag = /[-.]([A-Z0-9_]+)$/i.exec(prefix)?.[1].toUpperCase();
29
+ return { prefix, tag };
30
+ }
31
+ function isModelFile(path) {
32
+ const name = path.toLowerCase().split('/').at(-1);
33
+ return !name.includes('imatrix') && !sidecarNames.some(sidecar => name.includes(sidecar));
34
+ }
35
+ function fitOf(size, capacity) {
36
+ const needed = Number(size) * 1.15;
37
+ if (needed <= capacity.device)
38
+ return 'device';
39
+ if (needed <= capacity.device + capacity.host)
40
+ return 'host';
41
+ return 'none';
42
+ }
43
+ /** @param capacity Memory available for models on the host they would run on, used to say whether each quantization fits */
44
+ export async function details(repo, capacity, token) {
45
+ const [info, tree] = await Promise.all([
46
+ hubFetch(`api/models/${repo}?expand[]=baseModels`, token),
47
+ hubFetch(`api/models/${repo}/tree/main?recursive=true`, token),
48
+ ]);
49
+ const files = tree.filter(entry => entry.type == 'file' && entry.path.toLowerCase().endsWith('.gguf'));
50
+ const projectors = files.filter(file => file.path.toLowerCase().includes('mmproj'));
51
+ const projectorSize = projectors.length ? Math.min(...projectors.map(file => file.lfs?.size ?? file.size)) : 0;
52
+ const quants = new Map();
53
+ for (const file of files) {
54
+ if (!isModelFile(file.path))
55
+ continue;
56
+ const parsed = parseFileName(file.path);
57
+ if (!parsed.tag)
58
+ continue;
59
+ const existing = quants.get(parsed.tag);
60
+ if (existing && existing.prefix != parsed.prefix)
61
+ continue;
62
+ const quant = existing ?? { tag: parsed.tag, prefix: parsed.prefix, files: [], size: BigInt(projectorSize), fit: 'none' };
63
+ quant.files.push(file.path);
64
+ quant.size += BigInt(file.lfs?.size ?? file.size);
65
+ quants.set(parsed.tag, quant);
66
+ }
67
+ const base = info.baseModels?.relation == 'quantized' ? info.baseModels.models?.[0]?.id : undefined;
68
+ return {
69
+ repo: info.id,
70
+ base,
71
+ quants: [...quants.values()]
72
+ .map(({ prefix: _, ...quant }) => ({ ...quant, fit: fitOf(quant.size, capacity) }))
73
+ .sort((a, b) => Number(a.size - b.size)),
74
+ };
75
+ }
@@ -0,0 +1 @@
1
+ export * from './common.js';
package/dist/index.js ADDED
@@ -0,0 +1 @@
1
+ export * from './common.js';
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,104 @@
1
+ import * as z from 'zod';
2
+ import * as tools from '../tools.js';
3
+ /** Characters of a note's content shown when listing */
4
+ const previewLength = 200;
5
+ function summary(note, userId) {
6
+ const content = note.content ?? '';
7
+ return {
8
+ id: note.id,
9
+ title: note.title,
10
+ labels: note.labels,
11
+ pinned: note.pinned,
12
+ shared: note.userId != userId,
13
+ modified: note.modified,
14
+ preview: content.length > previewLength ? content.slice(0, previewLength) + '…' : content,
15
+ };
16
+ }
17
+ function details(note, userId) {
18
+ return {
19
+ id: note.id,
20
+ title: note.title,
21
+ content: note.content ?? '',
22
+ labels: note.labels,
23
+ pinned: note.pinned,
24
+ shared: note.userId != userId,
25
+ created: note.created,
26
+ modified: note.modified,
27
+ };
28
+ }
29
+ const Id = z.uuid().describe("The note's ID, from list_notes");
30
+ const Labels = z.string().max(30).array().max(20).describe('Short labels for grouping notes');
31
+ tools.add({
32
+ name: 'list_notes',
33
+ description: "Lists the user's notes, including ones shared with them, pinned first then most recently changed. " +
34
+ 'Contents are previews; use read_note for the whole note.',
35
+ environment: 'account',
36
+ access: 'read',
37
+ input: z.object({
38
+ query: z.string().max(200).optional().describe('Only notes whose title or content contains this, ignoring case'),
39
+ label: z.string().max(30).optional().describe('Only notes with this label'),
40
+ }),
41
+ async run({ query, label }, { api, userId }) {
42
+ const search = query?.toLowerCase();
43
+ return (await api('GET', 'users/:id/notes', {}, userId))
44
+ .filter(note => !label || note.labels.includes(label))
45
+ .filter(note => !search || note.title.toLowerCase().includes(search) || note.content?.toLowerCase().includes(search))
46
+ .slice(0, 50)
47
+ .map(note => summary(note, userId));
48
+ },
49
+ });
50
+ tools.add({
51
+ name: 'read_note',
52
+ description: 'Reads a whole note.',
53
+ environment: 'account',
54
+ access: 'read',
55
+ input: z.object({ id: Id }),
56
+ async run({ id }, { api, userId }) {
57
+ return details(await api('GET', 'notes/:id', {}, id), userId);
58
+ },
59
+ });
60
+ tools.add({
61
+ name: 'create_note',
62
+ description: 'Creates a note.',
63
+ environment: 'account',
64
+ access: 'write',
65
+ approval: 'allow',
66
+ input: z.object({
67
+ title: z.string().max(100),
68
+ content: z.string().max(10_000).optional().describe('Plain text or Markdown'),
69
+ labels: Labels.optional(),
70
+ pinned: z.boolean().optional(),
71
+ }),
72
+ async run(init, { api, userId }) {
73
+ return details(await api('PUT', 'users/:id/notes', { labels: [], pinned: false, ...init }, userId), userId);
74
+ },
75
+ });
76
+ tools.add({
77
+ name: 'update_note',
78
+ description: 'Changes a note. Only the given fields change; `content` replaces the whole content, so read the note first to edit part of it.',
79
+ environment: 'account',
80
+ access: 'write',
81
+ input: z.object({
82
+ id: Id,
83
+ title: z.string().max(100).optional(),
84
+ content: z.string().max(10_000).optional().describe('The new content, replacing the old'),
85
+ labels: Labels.optional().describe('The new labels, replacing the old'),
86
+ pinned: z.boolean().optional(),
87
+ }),
88
+ async run({ id, ...changes }, { api, userId }) {
89
+ const note = await api('GET', 'notes/:id', {}, id);
90
+ const { title, content, labels, pinned } = { ...note, ...changes };
91
+ return details(await api('PATCH', 'notes/:id', { title, content, labels, pinned }, id), userId);
92
+ },
93
+ });
94
+ tools.add({
95
+ name: 'delete_note',
96
+ description: 'Deletes a note permanently.',
97
+ environment: 'account',
98
+ access: 'write',
99
+ input: z.object({ id: Id }),
100
+ async run({ id }, { api }) {
101
+ const note = await api('DELETE', 'notes/:id', {}, id);
102
+ return { deleted: { id: note.id, title: note.title } };
103
+ },
104
+ });
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,157 @@
1
+ import * as z from 'zod';
2
+ import * as tools from '../tools.js';
3
+ function task(task) {
4
+ return {
5
+ id: task.id,
6
+ summary: task.summary,
7
+ description: task.description ?? undefined,
8
+ completed: !!task.completed,
9
+ parent: task.parentId ?? undefined,
10
+ };
11
+ }
12
+ function list(list, includeCompleted) {
13
+ const tasks = list.tasks ?? [];
14
+ const shown = includeCompleted ? tasks : tasks.filter(task => !task.completed);
15
+ return {
16
+ id: list.id,
17
+ name: list.name,
18
+ description: list.description ?? undefined,
19
+ shared: list.isShared,
20
+ tasks: shown.map(task),
21
+ ...(shown.length < tasks.length && { completedHidden: tasks.length - shown.length }),
22
+ };
23
+ }
24
+ /** Finds a task list by ID or name, ignoring case for names */
25
+ async function findList({ api, userId }, idOrName) {
26
+ const lists = await api('GET', 'users/:id/task_lists', {}, userId);
27
+ const name = idOrName.trim().toLowerCase();
28
+ const found = lists.find(list => list.id == idOrName) ?? lists.find(list => list.name.trim().toLowerCase() == name);
29
+ if (found)
30
+ return found;
31
+ const available = lists.map(list => `"${list.name}"`).join(', ') || 'none';
32
+ throw new Error(`No task list has the ID or name "${idOrName}". The user's task lists: ${available}`);
33
+ }
34
+ /** Finds a task by ID, explaining what went wrong when the ID belongs to something else */
35
+ async function findTask({ api, userId }, id) {
36
+ const lists = await api('GET', 'users/:id/task_lists', {}, userId);
37
+ for (const list of lists) {
38
+ const found = list.tasks.find(task => task.id == id);
39
+ if (found)
40
+ return found;
41
+ }
42
+ const list = lists.find(list => list.id == id);
43
+ if (list)
44
+ throw new Error(`${id} is the ID of the task list "${list.name}", not a task. Use the task list tools for lists.`);
45
+ throw new Error(`No task has the ID ${id}. Use list_tasks to find the task.`);
46
+ }
47
+ const TaskId = z.uuid().describe("The task's ID, from list_tasks");
48
+ const List = z.string().min(1).max(100).describe("The task list's ID or exact name");
49
+ const Summary = z.string().min(1).max(100).describe('A short summary of the task');
50
+ const Description = z.string().max(500).describe('More details');
51
+ const Parent = z.uuid().describe('The ID of the task this one is a subtask of');
52
+ tools.add({
53
+ name: 'list_tasks',
54
+ description: "Lists the user's task lists, including ones shared with them, with their tasks. " +
55
+ 'Subtasks have the ID of their parent task. Completed tasks are left out unless asked for.',
56
+ environment: 'account',
57
+ access: 'read',
58
+ input: z.object({
59
+ list: List.optional().describe('Only this task list, by ID or exact name'),
60
+ includeCompleted: z.boolean().optional().describe('Also list completed tasks'),
61
+ }),
62
+ async run({ list: idOrName, includeCompleted = false }, context) {
63
+ if (idOrName)
64
+ return list(await findList(context, idOrName), includeCompleted);
65
+ return (await context.api('GET', 'users/:id/task_lists', {}, context.userId)).map(entry => list(entry, includeCompleted));
66
+ },
67
+ });
68
+ tools.add({
69
+ name: 'add_task',
70
+ description: 'Adds a task to a task list.',
71
+ environment: 'account',
72
+ access: 'write',
73
+ approval: 'allow',
74
+ input: z.object({
75
+ list: List,
76
+ summary: Summary,
77
+ description: Description.optional(),
78
+ parent: Parent.optional(),
79
+ }),
80
+ async run({ list: idOrName, summary, description, parent }, context) {
81
+ const { id } = await findList(context, idOrName);
82
+ return task(await context.api('PUT', 'task_lists/:id', { summary, description, parentId: parent }, id));
83
+ },
84
+ });
85
+ tools.add({
86
+ name: 'update_task',
87
+ description: 'Changes a task, e.g. to mark it completed. Only the given fields change.',
88
+ environment: 'account',
89
+ access: 'write',
90
+ input: z.object({
91
+ id: TaskId,
92
+ summary: Summary.optional(),
93
+ description: Description.nullable().optional().describe('More details, or null to remove them'),
94
+ completed: z.boolean().optional(),
95
+ parent: Parent.nullable().optional().describe('The ID of the task this one is a subtask of, or null to make it a top-level task'),
96
+ }),
97
+ async run({ id, parent, ...changes }, context) {
98
+ await findTask(context, id);
99
+ return task(await context.api('PATCH', 'tasks/:id', { ...changes, ...(parent !== undefined && { parentId: parent }) }, id));
100
+ },
101
+ });
102
+ tools.add({
103
+ name: 'delete_task',
104
+ description: 'Deletes a task permanently. To delete a whole task list, use delete_task_list.',
105
+ environment: 'account',
106
+ access: 'write',
107
+ input: z.object({ id: TaskId }),
108
+ async run({ id }, context) {
109
+ await findTask(context, id);
110
+ const deleted = await context.api('DELETE', 'tasks/:id', {}, id);
111
+ return { deleted: { id: deleted.id, summary: deleted.summary } };
112
+ },
113
+ });
114
+ tools.add({
115
+ name: 'create_task_list',
116
+ description: 'Creates a task list.',
117
+ environment: 'account',
118
+ access: 'write',
119
+ approval: 'allow',
120
+ input: z.object({
121
+ name: z.string().min(1).max(50),
122
+ description: z.string().max(500).optional(),
123
+ }),
124
+ async run(init, { api, userId }) {
125
+ const created = await api('PUT', 'users/:id/task_lists', init, userId);
126
+ return { id: created.id, name: created.name };
127
+ },
128
+ });
129
+ tools.add({
130
+ name: 'update_task_list',
131
+ description: 'Renames a task list or changes its description. Only the given fields change.',
132
+ environment: 'account',
133
+ access: 'write',
134
+ input: z.object({
135
+ list: List,
136
+ name: z.string().min(1).max(50).optional().describe('The new name'),
137
+ description: z.string().max(500).nullable().optional().describe('The new description, or null to remove it'),
138
+ }),
139
+ async run({ list: idOrName, ...changes }, context) {
140
+ const existing = await findList(context, idOrName);
141
+ const { name, description } = { name: existing.name, description: existing.description, ...changes };
142
+ const updated = await context.api('PATCH', 'task_lists/:id', { name, description }, existing.id);
143
+ return { id: updated.id, name: updated.name, description: updated.description ?? undefined };
144
+ },
145
+ });
146
+ tools.add({
147
+ name: 'delete_task_list',
148
+ description: 'Deletes a task list and all of its tasks permanently.',
149
+ environment: 'account',
150
+ access: 'write',
151
+ input: z.object({ list: List }),
152
+ async run({ list: idOrName }, context) {
153
+ const { id } = await findList(context, idOrName);
154
+ const deleted = await context.api('DELETE', 'task_lists/:id', {}, id);
155
+ return { deleted: { id: deleted.id, name: deleted.name } };
156
+ },
157
+ });
package/dist/loop.d.ts ADDED
@@ -0,0 +1,75 @@
1
+ import type * as ai from './common.js';
2
+ import * as memory from './memory.js';
3
+ import './timers.js';
4
+ import type { ChatMessage, ChatRequest, ChatStream } from './node/chat.js';
5
+ import * as tools from './tools.js';
6
+ export type MessageChanges = Partial<Omit<ai.Message, 'id' | 'conversationId' | 'created'>>;
7
+ /** Where a conversation's messages are kept. Changes should reach the user. */
8
+ export interface Store {
9
+ userId: string;
10
+ conversationId: string;
11
+ add(message: MessageChanges & Pick<ai.Message, 'role'>): Promise<ai.Message>;
12
+ update(id: string, changes: MessageChanges): Promise<ai.Message>;
13
+ }
14
+ /** The text streamed into the message being generated, which is only saved once it ends */
15
+ export interface Progress {
16
+ messageId: string;
17
+ content: string;
18
+ reasoning: string;
19
+ }
20
+ /** What the loop needs to know about the model */
21
+ export interface ModelSettings extends Pick<ai.ModelInfo, 'id' | 'systemPrompt' | 'reasoning' | 'tools'> {
22
+ }
23
+ export interface TurnInit {
24
+ store: Store;
25
+ model: ModelSettings;
26
+ /** The conversation's reasoning setting */
27
+ reasoning: string;
28
+ /** Used when the model has no system prompt */
29
+ defaultSystemPrompt: string;
30
+ /** Calls with more steps than this get no tools, so the model has to answer */
31
+ maxSteps: number;
32
+ /** Runs a chat completion with the model */
33
+ complete(request: Omit<ChatRequest, 'model'>): ChatStream;
34
+ preferences: ai.Preferences;
35
+ /** The user's memories, or nothing when they shouldn't be used */
36
+ memories?: memory.Node[];
37
+ /** Tools act with this; its signal also cancels the turn */
38
+ context: tools.Context;
39
+ /** The pending assistant message to respond with */
40
+ pending: ai.Message;
41
+ /** The conversation before `pending`, oldest first */
42
+ history(): Promise<ai.Message[]>;
43
+ /** For tool calls awaiting the user; calls without a decision are denied */
44
+ decisions?: ai.Decisions;
45
+ /** Names of tools the user allowed for the rest of the conversation */
46
+ allowedTools: string[];
47
+ /** Saves tools the user just allowed for the rest of the conversation */
48
+ allowForChat?(names: string[]): Promise<void>;
49
+ /** Saves tools the user allowed in every conversation */
50
+ allowAlways?(names: string[]): Promise<void>;
51
+ /** Leaves out tools that use the user's data */
52
+ anonymous?: boolean;
53
+ /** For conversations that are never saved, which never save memories */
54
+ temporary?: boolean;
55
+ /** Kept up to date with the text being streamed */
56
+ progress: Progress;
57
+ /** Called with each piece of streamed text, after `progress` is updated */
58
+ onText?(field: 'content' | 'reasoning', text: string, position: number): void;
59
+ /** Called after the turn's final response */
60
+ onDone?(content: string): void;
61
+ /** The time zone of the user's device. Defaults to UTC. */
62
+ timeZone?: string;
63
+ /** The user's home time zone, when they have one */
64
+ homeTimeZone?: string;
65
+ }
66
+ /**
67
+ * A message as the model sees it, or nothing for messages it shouldn't see
68
+ * @param timeZone Used for when user messages were sent
69
+ */
70
+ export declare function toChatMessage(message: ai.Message, timeZone?: string): ChatMessage | undefined;
71
+ /**
72
+ * Responds to a conversation, calling tools until the model gives a final answer or a call needs the user's approval.
73
+ * Never throws: failures are saved on the messages they affect.
74
+ */
75
+ export declare function respond(init: TurnInit): Promise<void>;
package/dist/loop.js ADDED
@@ -0,0 +1,239 @@
1
+ import * as io from 'ioium';
2
+ import * as memory from './memory.js';
3
+ import './timers.js';
4
+ import * as tools from './tools.js';
5
+ const toolGuidance = `\
6
+ You can call tools. Only call one when it helps with what the user asked.\
7
+ If a call fails, read the error and correct the input instead of repeating the same call.\
8
+ Never create, change or delete anything the user didn't ask for, even as a workaround.\
9
+ Only say an action was done when a tool result confirms it; if you could not do something, say so.`;
10
+ const voiceGuidance = `\
11
+ The user is speaking to you, and your reply will be read aloud by a speech synthesizer, so write only what should be heard.\
12
+ Reply in plain spoken prose: no Markdown, lists, tables, headings, code, emoji, URLs or symbols that would be read out literally.\
13
+ Be brief and conversational, usually one to three sentences.\
14
+ Write numbers, dates, times and units the way they are said aloud, e.g. "twenty past three" and "about four kilometres".\
15
+ Don't read out IDs, links, file paths or long values; describe them, or say the details are in the chat.\
16
+ Only state facts you are sure of or that a tool result gave you; if you don't know, say so briefly.\
17
+ The transcript of what the user said may contain recognition mistakes, so read it for its likely meaning`;
18
+ /** When a message was sent, e.g. `<sent>Monday 2026-11-16T21:15-06:00 (2026-11-17T03:15Z)</sent>` */
19
+ function sentTag(created, timeZone) {
20
+ const instant = created.toTemporalInstant();
21
+ const local = instant.toZonedDateTimeISO(timeZone);
22
+ const weekday = local.toLocaleString('en-US', { weekday: 'long' });
23
+ const localText = local.toString({ smallestUnit: 'minute', timeZoneName: 'never' });
24
+ return `<sent>${weekday} ${localText} (${instant.toString({ smallestUnit: 'minute' })})</sent>`;
25
+ }
26
+ function systemPrompt({ prompt, instructions, offered, remembered, voice, timeZone, homeTimeZone }) {
27
+ const sections = [prompt];
28
+ // date information
29
+ const local = Temporal.Now.zonedDateTimeISO(timeZone);
30
+ const date = local.toLocaleString('en-US', { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' });
31
+ sections.push(`For the user, today is ${date}. Their time zone is ${timeZone} (UTC${local.offset}).\
32
+ ${homeTimeZone && homeTimeZone != timeZone ? ` Their home time zone is ${homeTimeZone}.` : ''}\
33
+ Each of the user's messages starts with a <sent> tag saying when it was sent,\
34
+ in their time and UTC; the latest one is the current time.\
35
+ The tag isn't part of what they wrote, so don't repeat it.`);
36
+ if (offered.length)
37
+ sections.push(toolGuidance);
38
+ if (remembered)
39
+ sections.push(remembered);
40
+ if (voice)
41
+ sections.push(voiceGuidance);
42
+ if (instructions)
43
+ sections.push(`The user has given these instructions for every conversation:\n\n${instructions}`);
44
+ return sections.join('\n\n');
45
+ }
46
+ /**
47
+ * A message as the model sees it, or nothing for messages it shouldn't see
48
+ * @param timeZone Used for when user messages were sent
49
+ */
50
+ export function toChatMessage(message, timeZone = 'UTC') {
51
+ switch (message.role) {
52
+ case 'user':
53
+ return { role: 'user', content: `${sentTag(message.created, timeZone)}\n${message.content}` };
54
+ case 'tool':
55
+ return {
56
+ role: 'tool',
57
+ tool_call_id: message.toolCallId,
58
+ content: message.status == 'cancelled' ? 'Cancelled by the user.' : message.content,
59
+ };
60
+ case 'assistant':
61
+ if (message.status == 'error' || (!message.content && !message.toolCalls?.length))
62
+ return;
63
+ return {
64
+ role: 'assistant',
65
+ content: message.content || null,
66
+ tool_calls: message.toolCalls?.map(call => ({
67
+ id: call.id,
68
+ type: 'function',
69
+ function: { name: call.name, arguments: call.arguments },
70
+ })),
71
+ };
72
+ }
73
+ }
74
+ const repeatedFailure = {
75
+ status: 'error',
76
+ content: 'Error: this exact call already failed. Change the input or answer without it.',
77
+ error: 'Repeated a failed call',
78
+ };
79
+ /**
80
+ * Runs or denies the tool calls in `history` that await the user, replacing them with the results.
81
+ * Tools the user allowed beyond this call are added to `allowed` and saved.
82
+ */
83
+ async function resolveAwaiting(history, init, allowed) {
84
+ const calls = new Map(history.flatMap(message => message.toolCalls ?? []).map(call => [call.id, call]));
85
+ const forChat = new Set();
86
+ const always = new Set();
87
+ for (const [index, message] of history.entries()) {
88
+ if (message.role != 'tool' || message.status != 'awaiting')
89
+ continue;
90
+ const call = calls.get(message.toolCallId);
91
+ const decision = call && init.decisions?.[call.id];
92
+ if (!call || !decision || decision == 'deny') {
93
+ history[index] = await init.store.update(message.id, {
94
+ status: 'error',
95
+ content: 'The user denied this action.',
96
+ error: 'Denied',
97
+ });
98
+ continue;
99
+ }
100
+ if (decision == 'chat')
101
+ forChat.add(call.name);
102
+ if (decision == 'always')
103
+ always.add(call.name);
104
+ history[index] = await init.store.update(message.id, await tools.run(tools.get(call.name), call, init.context));
105
+ }
106
+ for (const name of forChat)
107
+ allowed.add(name);
108
+ if (forChat.size)
109
+ await init.allowForChat?.([...allowed]);
110
+ if (always.size)
111
+ await init.allowAlways?.([...always]);
112
+ }
113
+ /** Anything more than this is probably a bug. */
114
+ const stepUpperBound = 1000;
115
+ /**
116
+ * Responds to a conversation, calling tools until the model gives a final answer or a call needs the user's approval.
117
+ * Never throws: failures are saved on the messages they affect.
118
+ */
119
+ export async function respond(init) {
120
+ const { store, model, preferences, context, progress } = init;
121
+ const { signal } = context;
122
+ /** The assistant message being streamed into, until it finishes */
123
+ let pending = init.pending;
124
+ /** Tool messages whose calls are running */
125
+ const running = new Set();
126
+ function append(field, text) {
127
+ const position = progress[field].length;
128
+ progress[field] += text;
129
+ init.onText?.(field, text, position);
130
+ }
131
+ try {
132
+ const offered = model.tools === false ? [] : tools.allowed(preferences.tools, { anonymous: init.anonymous, temporary: init.temporary });
133
+ const definitions = tools.definitions(offered);
134
+ const remembered = init.memories &&
135
+ memory.prompt(init.memories, offered.some(tool => tool.environment == 'memory' && tool.access == 'write'));
136
+ const allowed = new Set(init.allowedTools);
137
+ const history = await init.history();
138
+ await resolveAwaiting(history, init, allowed);
139
+ const spoken = !!history.findLast(message => message.role == 'user')?.voice;
140
+ const reasoning = spoken ? 'none' : init.reasoning == 'default' ? (model.reasoning ?? 'default') : init.reasoning;
141
+ const timeZone = init.timeZone ?? 'UTC';
142
+ const messages = [
143
+ {
144
+ role: 'system',
145
+ content: systemPrompt({
146
+ prompt: model.systemPrompt ?? init.defaultSystemPrompt,
147
+ instructions: preferences.instructions?.trim(),
148
+ offered,
149
+ remembered,
150
+ voice: spoken,
151
+ timeZone,
152
+ homeTimeZone: init.homeTimeZone,
153
+ }),
154
+ },
155
+ ...history.map(message => toChatMessage(message, timeZone)).filter(message => !!message),
156
+ ];
157
+ /** Calls that failed, by name and arguments */
158
+ const failed = new Set();
159
+ for (let step = 1; step < stepUpperBound; step++) {
160
+ const stream = init.complete({
161
+ messages,
162
+ reasoning,
163
+ tools: step < init.maxSteps ? definitions : undefined,
164
+ signal,
165
+ });
166
+ let chunk = await stream.next();
167
+ for (; !chunk.done; chunk = await stream.next())
168
+ append(chunk.value.field, chunk.value.text);
169
+ const result = chunk.value;
170
+ const calls = result.toolCalls
171
+ .filter(call => call.name)
172
+ .map(call => ({ ...call, id: call.id || 'call_' + crypto.randomUUID() }));
173
+ const finished = await store.update(pending.id, {
174
+ content: result.content,
175
+ reasoning: result.reasoning || null,
176
+ toolCalls: calls.length ? calls : null,
177
+ status: 'done',
178
+ usage: result.usage,
179
+ });
180
+ pending = null;
181
+ if (!calls.length) {
182
+ init.onDone?.(result.content);
183
+ return;
184
+ }
185
+ messages.push(toChatMessage(finished));
186
+ let awaiting = false;
187
+ const queue = [];
188
+ for (const call of calls) {
189
+ const tool = tools.get(call.name);
190
+ const approval = tools.needsApproval(tool, preferences.tools, allowed);
191
+ const message = await store.add({ role: 'tool', toolCallId: call.id, status: approval ? 'awaiting' : 'pending' });
192
+ if (approval)
193
+ awaiting = true;
194
+ else {
195
+ running.add(message.id);
196
+ queue.push({ call, tool, message });
197
+ }
198
+ }
199
+ for (const { call, tool, message } of queue) {
200
+ signal.throwIfAborted();
201
+ const key = call.name + '\n' + call.arguments;
202
+ const outcome = failed.has(key) ? repeatedFailure : await tools.run(tool, call, context);
203
+ if (outcome.status == 'error')
204
+ failed.add(key);
205
+ const done = await store.update(message.id, signal.aborted ? { status: 'cancelled' } : outcome);
206
+ running.delete(message.id);
207
+ messages.push(toChatMessage(done));
208
+ }
209
+ signal.throwIfAborted();
210
+ if (awaiting)
211
+ return;
212
+ pending = await store.add({ role: 'assistant', status: 'pending' });
213
+ Object.assign(progress, { messageId: pending.id, content: '', reasoning: '' });
214
+ }
215
+ }
216
+ catch (error) {
217
+ const isTimeout = (value) => value instanceof Error && value.name == 'TimeoutError';
218
+ const timedOut = isTimeout(signal.reason) || isTimeout(error);
219
+ const cancelled = signal.aborted && !timedOut;
220
+ if (!cancelled)
221
+ io.warn(`AI: response in ${store.conversationId} failed: ${io.errorText(error)}`);
222
+ const reason = cancelled ? null : timedOut ? 'Timed out' : io.errorText(error);
223
+ try {
224
+ for (const id of running)
225
+ await store.update(id, { status: cancelled ? 'cancelled' : 'error', error: reason });
226
+ if (pending) {
227
+ await store.update(pending.id, {
228
+ content: progress.content,
229
+ reasoning: progress.reasoning || null,
230
+ status: cancelled ? 'cancelled' : 'error',
231
+ error: reason,
232
+ });
233
+ }
234
+ }
235
+ catch (error) {
236
+ io.error(`AI: could not finish response in ${store.conversationId}: ${io.errorText(error)}`);
237
+ }
238
+ }
239
+ }