Skip to content

Changelog

All packages share one version. npm packages are published under @aidy-dev; the Python kit is aidy on PyPI.

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.

  • aidy.citation is {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.citations holds Citation[] (@aidy-dev/client).
  • aidy.model.retry carries endpoint and fallback.
  • 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_unavailable comes only when none is left; a rate-limited endpoint is no longer retried when all rest. See Models.
  • SearchHit has content (model-only); FederatedHit and citation hits exclude it. fuse returns FusedHit (with content).
  • Search operations default to a 2 s timeout and accept x-aidy.timeoutSeconds up to 10; a larger value is a catalog error.
  • @aidy-dev/client: ClientOptions.baseUrl is where aidy is mounted and optional (default ''); RunRequest.message is string | ContentPart[]; UserItem.attachments is required; ModelEndpointUpdate.id is required.
  • @aidy-dev/react: locale is any string and the Locale type is gone (Strings and locales replace it).
  • CLI: the built-in whoami is now status.
  • Store: putFeedback, listFeedback and deleteSettings are new required methods; SQL migration 002_feedback.
  • Conformance runner: RuntimeEnv.model is RuntimeEnv.endpoints.
  • Host jobs: POST /aidy/v0/generate, signed with an Aidy-Host-Assertion for op generate, takes {instructions?, input, schema?, maxOutputTokens?} and answers {text} or {object} (validated against schema, one repair attempt, else 422 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-endpoint temperature and maxOutputTokens. One chain per instance, shared by runs and host jobs.
  • Images and attachments: user messages take AG-UI text, image and document parts (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 context is added to that run’s system prompt (at most 16 entries, 8000 characters).
  • Async instructions: instructions may be an async function of the identity.
  • Search: per-source timeouts (x-aidy.timeoutSeconds, SearchSource.timeoutMs); hit content reaches the model through the search tool and MCP, never /search or 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 (up or down, with a comment) and GET /aidy/v0/feedback for admins.
  • Info: GET /aidy/v0/info answers the assistant’s name.
  • Settings: DELETE /aidy/v0/settings restores the configured models; secret may be a list to rotate it (the first seals, all unseal, old settings are sealed again); unreadable settings answer 503 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 need Content-Type; a body must be JSON.
  • Generated documents: skill.name (a valid slug even for non-ASCII product names), and skill.cli: {command, package?, install?}, named in /skill.md and /llms.txt.
  • Keys: importSigningKey and portableJwk; importPublicKeys accepts Node-exported JWKs (alg), which workerd refused.
  • 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, locale and strings (exported Strings and locales; unknown locales fall back to English), and the assistant name from GET /info.
  • AidyDock remembers its open state and thread per client baseUrl, and takes controlled open/onOpenChange and threadId/onThreadChange.
  • SearchPalette: controlled open/onOpenChange, useSearchPalette(), onAsk, and type labels through strings (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-root theme 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 with aidy 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 --host is optional.
  • Host commands win over built-ins, which stay reachable as aidy:<name>.
  • Every command takes --help.
  • aidy keys generate and aidy-server keys write portable JWKs.
  • Server environment: AIDY_SKILL_NAME, AIDY_CLI_COMMAND, AIDY_CLI_PACKAGE, AIDY_CLI_INSTALL, AIDY_PREVIOUS_SECRET.

See CLI and Deploy.

  • SearchHit.content.
  • Wire models show their real camelCase JSON Schema in FastAPI’s OpenAPI, and still omit absent fields.
  • Cases can script a model chain (endpoints, a turn’s endpoint), 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.

The first release.

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+.
  • Catalog. x-aidy on OpenAPI 3.1 operations, with closed validation, defaults from the HTTP method, and roles identity, search and form. See x-aidy.
  • Delegation. Every call to the host carries the user’s own credential and an EdDSA Aidy-Assertion bound 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’s request_input; name-or-id resolution; follow-up calls with next.
  • Deferred tasks. Operations that answer 202 {"aidyTask"}, completed by the host with an Aidy-Host-Assertion.
  • AG-UI 1.0 stream with the aidy profile: monotonic seq per thread, replay with Last-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.txt and the operation reference.
  • Federated search over every role: search operation 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.
  • Hono and Express adapter packages: embed aidy with createAidy and nodeHandler as in the Hono and Express guides.
  • A Go host kit. Python is the only host kit.
  • Knowledge settings through PUT /aidy/v0/settings: settings hold the model chain only.
  • A Helm chart.