Changelog
All packages share one version. npm packages are published under @aidy-dev; the Python kit is aidy on PyPI.
0.2.0 (2026-11)
Section titled “0.2.0 (2026-11)”Gaps found by four product migrations: Acahti, Pipetil, kunzhiyuan and this site. aidy is pre-1.0, so a minor release may break APIs; each break is listed first.
Breaking
Section titled “Breaking”aidy.citationis{messageId, citations: [{n, hit}]}: each cited hit under the number the answer wrote. It was{messageId, hits}packed in order, so[11]or[2][4]linked the wrong hit.ThreadState.citationsholdsCitation[](@aidy-dev/client).aidy.model.retrycarriesendpointandfallback.- Model chain. Any failure not retried on the same endpoint (4xx such as 400, 401, 403 or 404, quota answers, 429, retries used up) rests the endpoint and falls through to the next. A resting endpoint is skipped, and
model_unavailablecomes only when none is left; a rate-limited endpoint is no longer retried when all rest. See Models. SearchHithascontent(model-only);FederatedHitand citation hits exclude it.fusereturnsFusedHit(withcontent).- Search operations default to a 2 s timeout and accept
x-aidy.timeoutSecondsup to 10; a larger value is a catalog error. @aidy-dev/client:ClientOptions.baseUrlis where aidy is mounted and optional (default'');RunRequest.messageisstring | ContentPart[];UserItem.attachmentsis required;ModelEndpointUpdate.idis required.@aidy-dev/react:localeis any string and theLocaletype is gone (Stringsandlocalesreplace it).- CLI: the built-in
whoamiis nowstatus. - Store:
putFeedback,listFeedbackanddeleteSettingsare new required methods; SQL migration002_feedback. - Conformance runner:
RuntimeEnv.modelisRuntimeEnv.endpoints.
Runtime (@aidy-dev/core, @aidy-dev/spec)
Section titled “Runtime (@aidy-dev/core, @aidy-dev/spec)”- Host jobs:
POST /aidy/v0/generate, signed with anAidy-Host-Assertionfor opgenerate, takes{instructions?, input, schema?, maxOutputTokens?}and answers{text}or{object}(validated againstschema, one repair attempt, else422 invalid_output), over the same model chain, without tools or a thread. See Host jobs. - Model chain: rest 6 h for quota-like answers (402, or a body matching quota, insufficient, exhausted or 401008), 60 s for 429, 5 min otherwise, overridable per endpoint with
cooldownSeconds: {quota, rateLimit, error}. Per-endpointtemperatureandmaxOutputTokens. One chain per instance, shared by runs and host jobs. - Images and attachments: user messages take AG-UI
text,imageanddocumentparts (at most 10 attachments). Images on the host are fetched with the user’s credential and inlined (at most 5 MB); other URLs pass through; images go to vision endpoints only, others get a note. Text-like documents are read as text. Every attachment is named for the model with its URL. See User messages. - Page context: the run’s AG-UI
contextis added to that run’s system prompt (at most 16 entries, 8000 characters). - Async instructions:
instructionsmay be an async function of the identity. - Search: per-source timeouts (
x-aidy.timeoutSeconds,SearchSource.timeoutMs); hitcontentreaches the model through thesearchtool and MCP, never/searchor citations. - Tool errors: a failed host call gives the model the host’s redacted error body as
error.detail(at most 4 KB). - Feedback:
PUT /aidy/v0/threads/{id}/messages/{messageId}/feedback(upordown, with a comment) andGET /aidy/v0/feedbackfor admins. - Info:
GET /aidy/v0/infoanswers the assistant’sname. - Settings:
DELETE /aidy/v0/settingsrestores the configured models;secretmay be a list to rotate it (the first seals, all unseal, old settings are sealed again); unreadable settings answer503 settings_unreadable. - Host assertions are bound to aidy’s public origin plus the path, so tasks and host jobs work behind a proxy.
- Requests without a body (
DELETE, cancel) no longer needContent-Type; a body must be JSON. - Generated documents:
skill.name(a valid slug even for non-ASCII product names), andskill.cli: {command, package?, install?}, named in/skill.mdand/llms.txt. - Keys:
importSigningKeyandportableJwk;importPublicKeysaccepts Node-exported JWKs (alg), which workerd refused.
Knowledge (@aidy-dev/knowledge)
Section titled “Knowledge (@aidy-dev/knowledge)”- Explicit heading ids
## Title {#anchor}set the anchor and are stripped from the title. - Hits carry the chunk text as
content.
Client and React (@aidy-dev/client, @aidy-dev/react)
Section titled “Client and React (@aidy-dev/client, @aidy-dev/react)”- Client:
run(threadId, {message, context?, resume?}),attachmentPart,attachmentsOf,info,setFeedback,listFeedback,resetSettings,baseUrl. AidyProvider:upload(attach button, drag and drop, paste; thumbnails in the thread),context,localeandstrings(exportedStringsandlocales; unknown locales fall back to English), and the assistant name fromGET /info.AidyDockremembers its open state and thread per clientbaseUrl, and takes controlledopen/onOpenChangeandthreadId/onThreadChange.SearchPalette: controlledopen/onOpenChange,useSearchPalette(),onAsk, and type labels throughstrings(type.<type>).- Thumbs up and down with an optional comment on answers; “Reset to defaults” in
ModelSettings, whose new rows now get ids. - Every component carries the
.aidy-roottheme when used outside the dock, and the styles no longer depend on browser defaults that CSS resets (Tailwind preflight) remove.
See React.
CLI and server (@aidy-dev/cli, @aidy-dev/server)
Section titled “CLI and server (@aidy-dev/cli, @aidy-dev/server)”- Credentials from the environment (
AIDY_HOST/AIDY_TOKEN, or a brand’s own names withaidy brand --env-host --env-token); flags win over the environment over the saved login, and an environment token is never written to disk or printed. aidy brand --hostis optional.- Host commands win over built-ins, which stay reachable as
aidy:<name>. - Every command takes
--help. aidy keys generateandaidy-server keyswrite portable JWKs.- Server environment:
AIDY_SKILL_NAME,AIDY_CLI_COMMAND,AIDY_CLI_PACKAGE,AIDY_CLI_INSTALL,AIDY_PREVIOUS_SECRET.
Python kit (aidy)
Section titled “Python kit (aidy)”SearchHit.content.- Wire models show their real camelCase JSON Schema in FastAPI’s OpenAPI, and still omit absent fields.
Conformance
Section titled “Conformance”- Cases can script a model chain (
endpoints, a turn’sendpoint), check what the model sees (sees), send content parts and context, and script plain host requests, raw bodies and delays. New cases: model fall-through, quota rest, rate limit, every endpoint failing; host, external and no-vision images; page context; hit content; citation numbers; source timeout; host error bodies.
0.1.0 (2026-11)
Section titled “0.1.0 (2026-11)”The first release.
Packages
Section titled “Packages”| Package | Contents |
|---|---|
@aidy-dev/spec |
The language-neutral contract: the x-aidy catalog reader, delegation assertions, search fusion, and the AG-UI profile schemas. |
@aidy-dev/core |
The runtime and its Web-standard fetch handler (createAidy): threads, runs, approvals, forms, resolve, chains, AG-UI events, MCP, federated search, settings and generated documents. MemoryStore and SqlStore. |
@aidy-dev/sql |
The SqlDriver contract, drivers for Postgres, SQLite and Cloudflare D1, and a migration runner. |
@aidy-dev/documents |
Generators for skill.md, llms.txt, the operation reference and CLI command names. |
@aidy-dev/knowledge |
Markdown ingestion, heading-based chunking and BM25 search, with vectors when an embedder is given; a search source named knowledge. |
@aidy-dev/client |
A typed client of the HTTP API and a reducer from AG-UI events to thread state. |
@aidy-dev/react |
AidyDock, AidyThread, ApprovalCard, AidyForm, SearchPalette, HelpViewer and ModelSettings. |
@aidy-dev/server |
The aidy-server binary (serve, keys) that runs aidy beside a host in any language, configured by environment variables; nodeHandler for Express and node:http; the Docker image ghcr.io/aidy-dev/aidy-server. |
@aidy-dev/cli |
The aidy command: a generic MCP client of any aidy host, plus check, skill, llms, reference, docs, keys generate and brand. |
aidy (PyPI) |
The Python host kit: op(), AidyHost and AidyCall for FastAPI, verify_assertion, check_call, and the Identity and search models. Python 3.12+. |
Features
Section titled “Features”- Catalog.
x-aidyon OpenAPI 3.1 operations, with closed validation, defaults from the HTTP method, and rolesidentity,searchandform. See x-aidy. - Delegation. Every call to the host carries the user’s own credential and an EdDSA
Aidy-Assertionbound to the method, URL and body. Host-side verification in TypeScript and Python, checked against shared test vectors. - Approvals. Writes default to
approval: always. The approval is bound to the hash of the frozen arguments (RFC 8785), expires after 15 minutes and executes at most once. - Forms, resolve and chains. Host forms (
role: form) and the model’srequest_input; name-or-id resolution; follow-up calls withnext. - Deferred tasks. Operations that answer
202 {"aidyTask"}, completed by the host with anAidy-Host-Assertion. - AG-UI 1.0 stream with the aidy profile: monotonic
seqper thread, replay withLast-Event-ID, runs that outlive their connection. See Events. - MCP server at
/mcp: reads by default, writes only with elicitation confirmation; OAuth protected-resource metadata when configured. - CLI generated at run time from the host’s MCP tools, with branded wrappers.
- Generated documents:
/skill.md,/llms.txtand the operation reference. - Federated search over every
role: searchoperation and knowledge, merged by reciprocal rank fusion, with citations in answers. - Model chain over OpenAI-compatible, OpenAI and Anthropic providers or any AI SDK model, with cooldown on 402 and 429, and admin settings sealed at rest.
- Runtimes: embedded in JavaScript hosts on Node or Cloudflare Workers, or run beside any host with
aidy-server. - Conformance cases that pin every runtime behavior.