@nebutra/agents 1.0.0

package/AGENTS.md

@@ -0,0 +1,63 @@
+# AGENTS.md — packages/agents
+
+Execution contract for Nebutra's multi-agent runtime package.
+
+## Scope
+
+Applies to everything under `packages/ai/agents/`.
+
+This package owns agent lifecycle, orchestration, routing, tenant-aware memory,
+built-in tool stubs, and the shared AI SDK wrapper surface exported to the rest
+of the repo. It is the runtime layer for agent execution, not the place for
+app-specific prompts, UI behavior, or direct provider-specific business logic.
+
+## Source Of Truth
+
+- Public package surface and subpath exports: `package.json`, `src/index.ts`
+- Canonical agent and orchestration contracts: `src/types.ts`
+- Base agent lifecycle, memory loading, usage emission, and billing hook:
+  `src/agent.ts`
+- Multi-agent routing, quota checks, chat/pipeline/broadcast semantics:
+  `src/orchestrator.ts`, `src/router.ts`, `src/tenant.ts`
+- Built-in tool catalog and current stub behavior: `src/tools.ts`
+- Shared AI SDK wrapper config, model resolution, and provider helpers:
+  `src/sdk/`
+- Provider-specific runtime adapters: `src/providers/`
+- Public API coverage for exported surface: `src/__tests__/public-api.test.ts`
+
+Treat `README.md` as descriptive only. If docs drift, update the source files
+above instead of preserving outdated examples.
+
+## Contract Boundaries
+
+- Keep `package.json` exports and `src/index.ts` aligned. Do not ask consumers
+  to deep-import internals when a supported subpath export already exists.
+- Treat `src/types.ts` as the canonical contract for agent config, context,
+  memory, tool, usage, and orchestration semantics. Tightening these shapes is
+  a cross-package compatibility change.
+- Preserve the split between core runtime and provider adapters:
+  `src/agent.ts`, `src/orchestrator.ts`, and `src/router.ts` own generic agent
+  lifecycle semantics; `src/providers/` and `src/sdk/` own provider-specific
+  runtime behavior.
+- Keep quota and usage semantics centralized in `src/tenant.ts` and
+  `src/agent.ts`. Do not scatter billing deduction or quota checks into callers.
+- Keep built-in tools honest about current capability. `src/tools.ts` is still
+  stub-oriented; do not document or code against live search, RAG, or SQL
+  access unless the actual implementation is being added.
+- Memory semantics belong in `src/memory.ts` and the base lifecycle in
+  `src/agent.ts`. Do not invent parallel persistence paths in downstream apps.
+
+## Generated And Derived Files
+
+- Treat future `dist/` output from `tsup` as derived build output.
+- Do not hand-edit temporary runtime logs, cached memory snapshots, or ad hoc
+  generated provider metadata.
+- If public runtime behavior changes, update the source files above and rebuild
+  rather than patching emitted output.
+
+## Validation
+
+- Public API, routing, tool, or lifecycle changes:
+  `pnpm --filter @nebutra/agents test`
+- Export, type, or provider-surface changes:
+  `pnpm --filter @nebutra/agents typecheck`