@aidy-dev/core 0.1.0 → 0.2.1

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.
package/README.md CHANGED
@@ -6,6 +6,7 @@ Web-standard `fetch` handler:
6
6
  - the in-app agent over aidy's HTTP API and its AG-UI 1.0 profile (`/aidy/v0/*`),
7
7
  - an MCP server (`/mcp`),
8
8
  - federated search (`/aidy/v0/search`),
9
+ - one-shot completions for host jobs (`POST /aidy/v0/generate`, signed by the host),
9
10
  - generated agent documents (`/skill.md`, `/llms.txt`) and its public keys
10
11
  (`/.well-known/aidy-keys.json`).
11
12
 
@@ -17,13 +18,12 @@ contract it implements is in [`spec/`](../../spec); every behavior is pinned by
17
18
 
18
19
  ```ts
19
20
  import { createAidy, SqlStore } from '@aidy-dev/core';
21
+ import { importSigningKey } from '@aidy-dev/spec/delegation';
20
22
  import { sqliteDriver } from '@aidy-dev/sql/sqlite';
21
23
 
22
- const signingKey = {
23
- kid: 'aidy-1',
24
- // An Ed25519 private JWK from `aidy keys generate`; extractable, so the public key can be served.
25
- privateKey: await crypto.subtle.importKey('jwk', JSON.parse(process.env.AIDY_PRIVATE_JWK!), 'Ed25519', true, ['sign']),
26
- };
24
+ // An Ed25519 private JWK with its kid, from `aidy keys generate`. importSigningKey drops the
25
+ // members some runtimes refuse (Node's `alg`) and keeps the key extractable to publish it.
26
+ const signingKey = await importSigningKey(JSON.parse(process.env.AIDY_PRIVATE_JWK!));
27
27
 
28
28
  const aidy = createAidy({
29
29
  url: 'https://console.example.com',
@@ -50,7 +50,7 @@ public key ([delegation](../../spec/delegation.md)).
50
50
  ### Embedded in the host
51
51
 
52
52
  Pass the host's own handler as `host.fetch` to call it in process, and mount aidy under a
53
- prefix with `basePath`:
53
+ prefix with `basePath` (clients then use `createClient({ baseUrl: '/assistant' })`):
54
54
 
55
55
  ```ts
56
56
  const app = new Hono();
@@ -75,8 +75,17 @@ export default {
75
75
  };
76
76
  ```
77
77
 
78
- Any AI SDK provider model can join the chain, e.g. Workers AI:
79
- `{ id: 'workers-ai', languageModel: createWorkersAI({ binding: env.AI })('@cf/…'), vision: false }`.
78
+ Any AI SDK provider model can join the chain, e.g. Workers AI through the `agents` package:
79
+
80
+ ```ts
81
+ import { createAI } from 'agents/models/ai-sdk';
82
+
83
+ const chain = [{ id: 'workers-ai', languageModel: createAI({ binding: env.AI })('@cf/zai-org/glm-4.7-flash') }];
84
+ ```
85
+
86
+ Use `agents/models/ai-sdk` rather than `workers-ai-provider`: inside workerd,
87
+ `workers-ai-provider` 4.0.1 reads streamed tool-call arguments from two fields of each chunk and
88
+ interleaves them, so every tool call fails with `invalid_arguments`.
80
89
 
81
90
  ## Configuration
82
91
 
@@ -89,13 +98,14 @@ Any AI SDK provider model can join the chain, e.g. Workers AI:
89
98
  | `host.openapi` | Path or URL of the OpenAPI 3.1 document, read with each user's credential. |
90
99
  | `host.fetch` | In-process fetch for embedded hosts. |
91
100
  | `signingKey` | aidy's Ed25519 key for assertions. |
92
- | `hostKeys` | Host public keys allowed to complete deferred tasks. |
101
+ | `hostKeys` | Host public keys that may sign `Aidy-Host-Assertion`: deferred-task completions and `POST /aidy/v0/generate`. |
93
102
  | `secret` | 32+ bytes; seals settings (model API keys) with AES-GCM. |
94
103
  | `store` | `MemoryStore` or `SqlStore(driver)` over any `@aidy-dev/sql` driver. |
95
- | `models.chain` | Models tried in order; 402 rests a model 6 h, 429 rests it 60 s; turns with images go to `vision` models. Admins replace the chain through `PUT /aidy/v0/settings`. |
96
- | `instructions` | Extra system instructions, or a function of the user's identity. |
97
- | `sources` | Extra search sources (`SearchSource`), such as `@aidy-dev/knowledge`. |
98
- | `skill.guide` | Hand-written Markdown placed at the top of `/skill.md`. |
104
+ | `models.chain` | Endpoints tried in order. A failure not retried on the endpoint (any 4xx, a quota answer, retries used up) rests it and the next one answers: quota-like answers (402, or a body matching quota/insufficient/exhausted) 6 h, 429 60 s, others 5 min, per endpoint `cooldownSeconds: { quota, rateLimit, error }`. Each endpoint may set `temperature` and `maxOutputTokens`. Turns with images go to `vision` endpoints. Admins replace the chain through `PUT /aidy/v0/settings` and restore it with `DELETE`. |
105
+ | `instructions` | Extra system instructions, or a (possibly async) function of the user's identity. |
106
+ | `sources` | Extra search sources (`SearchSource`, with an optional `timeoutMs`, default 2000, at most 10 000), such as `@aidy-dev/knowledge`. |
107
+ | `skill` | `/skill.md`: `name` (the frontmatter slug), `guide` (Markdown placed first), `cli: { command, package?, install? }`, also named in `/llms.txt` (default `aidy`, `@aidy-dev/cli`; `install` is a free-form line that wins over `package`). |
108
+ | `name` | The assistant's display name (default `Aidy`), served at `GET /aidy/v0/info` for the UI. |
99
109
  | `limits` | `maxSteps` (16), `contextTokens` (128 000), `runTimeoutSeconds` (600). |
100
110
  | `mcp.authorizationServers` | Serves OAuth protected-resource metadata for MCP clients. |
101
111
 
package/dist/index.d.ts CHANGED
@@ -2,8 +2,8 @@ import "hono";
2
2
  import { Identity } from "@aidy-dev/spec/catalog";
3
3
  import { SigningKey, VerificationKeys } from "@aidy-dev/spec/delegation";
4
4
  import { Form } from "@aidy-dev/spec/protocol";
5
- import "zod";
6
5
  import { SearchHit } from "@aidy-dev/spec/search";
6
+ import "zod";
7
7
  import { LanguageModelV4, SharedV4ProviderOptions } from "@ai-sdk/provider";
8
8
  import { SqlDriver } from "@aidy-dev/sql";
9
9
  import { Interrupt, Message } from "@ag-ui/core";
@@ -108,6 +108,25 @@ interface TaskRecord {
108
108
  readonly status: TaskStatus;
109
109
  readonly result?: unknown;
110
110
  }
111
+ /** A user's rating of an assistant message; one per message, the latest wins. */
112
+ interface FeedbackRecord {
113
+ readonly threadId: string;
114
+ readonly messageId: string;
115
+ readonly owner: Owner;
116
+ readonly rating: 'up' | 'down';
117
+ readonly comment?: string;
118
+ /** When the rating was given (or last replaced), RFC 3339 UTC. */
119
+ readonly createdAt: string;
120
+ }
121
+ interface FeedbackQuery {
122
+ /** Only the feedback on threads of this tenant ('' or absent: of no tenant). */
123
+ readonly tenant?: string;
124
+ /** Only feedback given at or after this RFC 3339 UTC time. */
125
+ readonly since?: string;
126
+ /** The `next` of the previous page. */
127
+ readonly cursor?: string;
128
+ readonly limit: number;
129
+ }
111
130
  interface Store {
112
131
  /** Creates or upgrades the store's tables. */
113
132
  migrate(): Promise<void>;
@@ -148,51 +167,88 @@ interface Store {
148
167
  getTask(id: string): Promise<TaskRecord | undefined>;
149
168
  /** Completes a pending task; false when it was not pending. */
150
169
  completeTask(id: string, status: Exclude<TaskStatus, 'pending'>, result?: unknown): Promise<boolean>;
170
+ /** Records feedback, replacing the previous rating of the same message. */
171
+ putFeedback(record: FeedbackRecord): Promise<void>;
172
+ /** Feedback oldest first; `next` is the cursor of the following page. */
173
+ listFeedback(query: FeedbackQuery): Promise<{
174
+ items: FeedbackRecord[];
175
+ next?: string;
176
+ }>;
151
177
  /** The sealed settings document, if any. */
152
178
  getSettings(): Promise<string | undefined>;
153
179
  putSettings(sealed: string): Promise<void>;
180
+ deleteSettings(): Promise<void>;
181
+ }
182
+ /**
183
+ * How long an endpoint rests after a failure that moved the chain past it, in seconds:
184
+ * `quota` after 402 or an exhausted quota (default 6 h), `rateLimit` after 429 (60 s), `error`
185
+ * after any other failure (5 min).
186
+ */
187
+ interface CooldownSeconds {
188
+ quota?: number;
189
+ rateLimit?: number;
190
+ error?: number;
191
+ }
192
+ /** Settings every chain endpoint takes. */
193
+ interface EndpointOptions {
194
+ /** Used for turns with images; other endpoints get a note in place of each image. */
195
+ vision?: boolean;
196
+ /** Sampling temperature; the provider's default when unset. */
197
+ temperature?: number;
198
+ /** The most tokens one answer may have; the provider's default when unset. */
199
+ maxOutputTokens?: number;
200
+ cooldownSeconds?: CooldownSeconds;
154
201
  }
155
202
  /** A model aidy builds from an AI SDK provider package. */
156
- interface ProviderEndpoint {
203
+ interface ProviderEndpoint extends EndpointOptions {
157
204
  /** Stable id: settings keep an entry's API key by it. */
158
205
  id: string;
159
206
  provider: 'openai-compatible' | 'openai' | 'anthropic';
160
207
  model: string;
161
208
  baseURL?: string;
162
209
  apiKey?: string;
163
- /** Used for turns with images. */
164
- vision?: boolean;
165
210
  /** Passed to the provider, e.g. `{ "openai-compatible": { enable_thinking: false } }`. */
166
211
  providerOptions?: SharedV4ProviderOptions;
167
212
  }
168
213
  /** Any AI SDK provider model, e.g. Workers AI through `workers-ai-provider`. */
169
- interface CustomEndpoint {
214
+ interface CustomEndpoint extends EndpointOptions {
170
215
  /** Stable id, shown in settings. */
171
216
  id: string;
172
217
  languageModel: LanguageModelV4;
173
- vision?: boolean;
174
218
  }
175
219
  type ModelEndpoint = ProviderEndpoint | CustomEndpoint;
176
220
  interface ModelSettings {
177
221
  /**
178
- * Tried in order; a model answering 402 rests 6 h, one answering 429 rests 60 s. Turns with
179
- * images go only to `vision` models.
222
+ * Tried in order. An endpoint that fails in a way not retried on it rests (see
223
+ * `cooldownSeconds`) and the next one answers. Turns with images go to `vision` endpoints.
180
224
  */
181
225
  chain: ModelEndpoint[];
182
226
  }
183
227
  interface SearchSource {
184
228
  /** Matches OPERATION_NAME, e.g. "knowledge". */
185
229
  readonly name: string;
230
+ /** How long federated search waits for this source. Default 2000, at most 10000. */
231
+ readonly timeoutMs?: number;
186
232
  search(query: string, options: {
187
233
  limit: number;
188
234
  identity: Identity;
189
235
  }): Promise<SearchHit[]>;
190
236
  }
237
+ /** Instructions for the model, or a function of the user that answers them. */
238
+ type Instructions = string | ((identity: Identity) => string | Promise<string>);
191
239
  interface AidyConfig {
192
240
  /** Display name of the assistant. Default "Aidy". */
193
241
  name?: string;
194
242
  /** Public URL of this aidy instance (the assertion `iss`), e.g. https://console.example.com/aidy */
195
243
  url: string;
244
+ /**
245
+ * The product's name and summary for documents served to signed-out callers when the host's
246
+ * OpenAPI needs a sign-in. The catalog's `info.title` and `description` win when readable.
247
+ */
248
+ product?: {
249
+ name: string;
250
+ summary?: string;
251
+ };
196
252
  /** Prefix of every route when the host mounts aidy below its root, e.g. `/assistant`. */
197
253
  basePath?: string;
198
254
  host: {
@@ -209,17 +265,31 @@ interface AidyConfig {
209
265
  signingKey: SigningKey;
210
266
  /** Host public keys that may sign `Aidy-Host-Assertion` (deferred-task completion). */
211
267
  hostKeys?: VerificationKeys;
212
- /** 32+ byte secret used to seal settings (model API keys) at rest. */
213
- secret: string;
268
+ /**
269
+ * 32+ byte secret that seals settings (model API keys) at rest. To rotate it, give a list: the
270
+ * first seals, every one unseals, and settings sealed with an older one are sealed again.
271
+ */
272
+ secret: string | readonly string[];
214
273
  store: Store;
215
274
  /** Defaults; admins override them through /aidy/v0/settings. */
216
275
  models: ModelSettings;
217
- instructions?: string | ((identity: Identity) => string);
276
+ instructions?: Instructions;
218
277
  /** Extra search sources, e.g. knowledge. */
219
278
  sources?: SearchSource[];
220
- /** Hand-written markdown placed before the generated tool index of /skill.md. */
279
+ /** /skill.md: the hand-written guide placed before the generated sections, and the CLI it names. */
221
280
  skill?: {
222
- guide: string;
281
+ /** The skill's `name`; default the product's slug, else the host's first hostname label. */
282
+ name?: string;
283
+ guide?: string;
284
+ /**
285
+ * The CLI /skill.md and /llms.txt name, and how to install it: its npm `package`, or a
286
+ * free-form `install` line (which wins). Default `aidy` from `@aidy-dev/cli`.
287
+ */
288
+ cli?: {
289
+ command: string;
290
+ package?: string;
291
+ install?: string;
292
+ };
223
293
  };
224
294
  limits?: {
225
295
  maxSteps?: number;
@@ -250,6 +320,7 @@ export declare class MemoryStore implements Store {
250
320
  private readonly runs;
251
321
  private readonly interrupts;
252
322
  private readonly tasks;
323
+ private readonly feedback;
253
324
  private settings;
254
325
  migrate(): Promise<void>;
255
326
  createThread(thread: ThreadRecord): Promise<void>;
@@ -284,6 +355,12 @@ export declare class MemoryStore implements Store {
284
355
  completeTask(id: string, status: Exclude<TaskStatus, 'pending'>, result?: unknown): Promise<boolean>;
285
356
  getSettings(): Promise<string | undefined>;
286
357
  putSettings(sealed: string): Promise<void>;
358
+ deleteSettings(): Promise<void>;
359
+ putFeedback(record: FeedbackRecord): Promise<void>;
360
+ listFeedback(query: FeedbackQuery): Promise<{
361
+ items: FeedbackRecord[];
362
+ next?: string;
363
+ }>;
287
364
  }
288
365
  export declare class SqlStore implements Store {
289
366
  private readonly db;
@@ -321,5 +398,11 @@ export declare class SqlStore implements Store {
321
398
  completeTask(id: string, status: Exclude<TaskStatus, 'pending'>, result?: unknown): Promise<boolean>;
322
399
  getSettings(): Promise<string | undefined>;
323
400
  putSettings(sealed: string): Promise<void>;
401
+ deleteSettings(): Promise<void>;
402
+ putFeedback(record: FeedbackRecord): Promise<void>;
403
+ listFeedback(query: FeedbackQuery): Promise<{
404
+ items: FeedbackRecord[];
405
+ next?: string;
406
+ }>;
324
407
  }
325
- export type { Aidy, AidyConfig, AidyEvent, CitedHit, CustomEndpoint, ExecutionContext, InterruptRecord, InterruptStatus, ModelEndpoint, ModelSettings, Owner, PendingCall, PendingToolCall, ProviderEndpoint, RunRecord, RunState, RunStatus, SearchSource, Store, StoredEvent, TaskRecord, TaskStatus, ThreadRecord };
408
+ export type { Aidy, AidyConfig, AidyEvent, CitedHit, CooldownSeconds, CustomEndpoint, ExecutionContext, FeedbackQuery, FeedbackRecord, Instructions, InterruptRecord, InterruptStatus, ModelEndpoint, ModelSettings, Owner, PendingCall, PendingToolCall, ProviderEndpoint, RunRecord, RunState, RunStatus, SearchSource, Store, StoredEvent, TaskRecord, TaskStatus, ThreadRecord };