@aidy-dev/core 0.1.0 → 0.2.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.
- package/README.md +23 -13
- package/dist/index.d.ts +89 -14
- package/dist/index.js +1032 -270
- package/package.json +5 -4
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
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
-
|
|
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
|
|
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` |
|
|
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
|
|
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,46 +167,75 @@ 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
|
|
179
|
-
* images go
|
|
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;
|
|
@@ -209,17 +257,31 @@ interface AidyConfig {
|
|
|
209
257
|
signingKey: SigningKey;
|
|
210
258
|
/** Host public keys that may sign `Aidy-Host-Assertion` (deferred-task completion). */
|
|
211
259
|
hostKeys?: VerificationKeys;
|
|
212
|
-
/**
|
|
213
|
-
|
|
260
|
+
/**
|
|
261
|
+
* 32+ byte secret that seals settings (model API keys) at rest. To rotate it, give a list: the
|
|
262
|
+
* first seals, every one unseals, and settings sealed with an older one are sealed again.
|
|
263
|
+
*/
|
|
264
|
+
secret: string | readonly string[];
|
|
214
265
|
store: Store;
|
|
215
266
|
/** Defaults; admins override them through /aidy/v0/settings. */
|
|
216
267
|
models: ModelSettings;
|
|
217
|
-
instructions?:
|
|
268
|
+
instructions?: Instructions;
|
|
218
269
|
/** Extra search sources, e.g. knowledge. */
|
|
219
270
|
sources?: SearchSource[];
|
|
220
|
-
/**
|
|
271
|
+
/** /skill.md: the hand-written guide placed before the generated sections, and the CLI it names. */
|
|
221
272
|
skill?: {
|
|
222
|
-
|
|
273
|
+
/** The skill's `name`; default the product's slug, else the host's first hostname label. */
|
|
274
|
+
name?: string;
|
|
275
|
+
guide?: string;
|
|
276
|
+
/**
|
|
277
|
+
* The CLI /skill.md and /llms.txt name, and how to install it: its npm `package`, or a
|
|
278
|
+
* free-form `install` line (which wins). Default `aidy` from `@aidy-dev/cli`.
|
|
279
|
+
*/
|
|
280
|
+
cli?: {
|
|
281
|
+
command: string;
|
|
282
|
+
package?: string;
|
|
283
|
+
install?: string;
|
|
284
|
+
};
|
|
223
285
|
};
|
|
224
286
|
limits?: {
|
|
225
287
|
maxSteps?: number;
|
|
@@ -250,6 +312,7 @@ export declare class MemoryStore implements Store {
|
|
|
250
312
|
private readonly runs;
|
|
251
313
|
private readonly interrupts;
|
|
252
314
|
private readonly tasks;
|
|
315
|
+
private readonly feedback;
|
|
253
316
|
private settings;
|
|
254
317
|
migrate(): Promise<void>;
|
|
255
318
|
createThread(thread: ThreadRecord): Promise<void>;
|
|
@@ -284,6 +347,12 @@ export declare class MemoryStore implements Store {
|
|
|
284
347
|
completeTask(id: string, status: Exclude<TaskStatus, 'pending'>, result?: unknown): Promise<boolean>;
|
|
285
348
|
getSettings(): Promise<string | undefined>;
|
|
286
349
|
putSettings(sealed: string): Promise<void>;
|
|
350
|
+
deleteSettings(): Promise<void>;
|
|
351
|
+
putFeedback(record: FeedbackRecord): Promise<void>;
|
|
352
|
+
listFeedback(query: FeedbackQuery): Promise<{
|
|
353
|
+
items: FeedbackRecord[];
|
|
354
|
+
next?: string;
|
|
355
|
+
}>;
|
|
287
356
|
}
|
|
288
357
|
export declare class SqlStore implements Store {
|
|
289
358
|
private readonly db;
|
|
@@ -321,5 +390,11 @@ export declare class SqlStore implements Store {
|
|
|
321
390
|
completeTask(id: string, status: Exclude<TaskStatus, 'pending'>, result?: unknown): Promise<boolean>;
|
|
322
391
|
getSettings(): Promise<string | undefined>;
|
|
323
392
|
putSettings(sealed: string): Promise<void>;
|
|
393
|
+
deleteSettings(): Promise<void>;
|
|
394
|
+
putFeedback(record: FeedbackRecord): Promise<void>;
|
|
395
|
+
listFeedback(query: FeedbackQuery): Promise<{
|
|
396
|
+
items: FeedbackRecord[];
|
|
397
|
+
next?: string;
|
|
398
|
+
}>;
|
|
324
399
|
}
|
|
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 };
|
|
400
|
+
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 };
|