@retinue/agentkit 0.2.0 → 0.3.0

package/dist/entries/mcp-server.js

@@ -0,0 +1,9 @@
+/**
+ * `@retinue/agentkit/mcp-server` — expose this deployment's tools to MCP clients (#250).
+ *
+ * Its own subpath, and separate from `./mcp`, because the two are opposite directions: `./mcp` consumes a
+ * tenant's MCP servers, and this **is** one. Sharing an entry would put the SDK's server half in the way of
+ * every consumer who only wanted the client half.
+ */
+export * from "../mcp-server/index.js";
+//# sourceMappingURL=mcp-server.js.map

package/dist/entries/runtime.d.ts

@@ -10,4 +10,14 @@ export * from "../models/index.js";
 export * from "../capabilities/index.js";
 export * from "../capabilities/runtime.js";
 export * from "../core/index.js";
+/**
+ * The audio ports and their OpenAI adapters — REQ-062 (#257).
+ *
+ * Here rather than in `tools`, because a `TranscriptionProvider` is a runtime capability a host wires once —
+ * the same place a `SearchProvider` is chosen. The two tools that use them live in the tool library.
+ */
+export { assertWithinBounds, AUDIO_MEDIA_TYPES, AudioRejected, boundTranscript, describeAudioFailure, isAudioMediaType, MAX_AUDIO_BYTES, MAX_AUDIO_SECONDS, MAX_SPEECH_CHARS, MAX_TRANSCRIPT_CHARS, } from "../audio/index.js";
+export type { AudioBounds, AudioMediaType, SpeechProvider, SpeechRequest, SpeechResult, TranscriptionProvider, TranscriptionRequest, TranscriptionResult, } from "../audio/index.js";
+export { openAiSpeech, openAiTranscription } from "../adapters/audio/openai.js";
+export type { OpenAiAudioConfig } from "../adapters/audio/openai.js";
 //# sourceMappingURL=runtime.d.ts.map

package/dist/entries/runtime.js

@@ -10,4 +10,12 @@ export * from "../models/index.js";
 export * from "../capabilities/index.js";
 export * from "../capabilities/runtime.js";
 export * from "../core/index.js";
+/**
+ * The audio ports and their OpenAI adapters — REQ-062 (#257).
+ *
+ * Here rather than in `tools`, because a `TranscriptionProvider` is a runtime capability a host wires once —
+ * the same place a `SearchProvider` is chosen. The two tools that use them live in the tool library.
+ */
+export { assertWithinBounds, AUDIO_MEDIA_TYPES, AudioRejected, boundTranscript, describeAudioFailure, isAudioMediaType, MAX_AUDIO_BYTES, MAX_AUDIO_SECONDS, MAX_SPEECH_CHARS, MAX_TRANSCRIPT_CHARS, } from "../audio/index.js";
+export { openAiSpeech, openAiTranscription } from "../adapters/audio/openai.js";
 //# sourceMappingURL=runtime.js.map

package/dist/entries/testing.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@retinue/agentkit/testing` — the conformance suite and the fakes — task #253.
+ *
+ * The README's headline claim is *"Replaceable everything — 31 ports, three adapter families, one conformance
+ * suite held over all of them."* A consumer who took that invitation and wrote a fourth adapter family could not
+ * run the suite: it lived in `src/testing/`, which the build excluded and no export reached. The most valuable
+ * thing in the repository for anyone doing that was the one thing they could not have.
+ *
+ * ## Two audiences, one entry
+ *
+ * - **Implementing a port.** `<port>Conformance` runs the same contract tests the built-in families are held to.
+ *   That is what makes "replaceable" checkable rather than an invitation.
+ * - **Implementing an agent or a tool.** `createStubModel` and `createMemoryStores` are for a test that must not
+ *   call a provider or stand up a database.
+ *
+ * ## Why the test runner is an optional peer
+ *
+ * The harnesses call `describe`/`it`/`expect` at module scope, so importing this pulls `vitest`. It is an
+ * **optional peer dependency**, not a dependency: a consumer who never imports this subpath never installs it,
+ * and nothing in a production bundle can reach it — the only paths to these modules are through this entry.
+ * `@electric-sql/pglite` is optional for the same reason, and only `pgliteExecutor` needs it.
+ */
+export * from "../testing/conformance/index.js";
+export * from "../testing/stub-model.js";
+export * from "../testing/memory-backend.js";
+export * from "../testing/pglite.js";
+export * from "../testing/conformance/audio.js";
+//# sourceMappingURL=testing.d.ts.map

package/dist/entries/testing.js

@@ -0,0 +1,28 @@
+/**
+ * `@retinue/agentkit/testing` — the conformance suite and the fakes — task #253.
+ *
+ * The README's headline claim is *"Replaceable everything — 31 ports, three adapter families, one conformance
+ * suite held over all of them."* A consumer who took that invitation and wrote a fourth adapter family could not
+ * run the suite: it lived in `src/testing/`, which the build excluded and no export reached. The most valuable
+ * thing in the repository for anyone doing that was the one thing they could not have.
+ *
+ * ## Two audiences, one entry
+ *
+ * - **Implementing a port.** `<port>Conformance` runs the same contract tests the built-in families are held to.
+ *   That is what makes "replaceable" checkable rather than an invitation.
+ * - **Implementing an agent or a tool.** `createStubModel` and `createMemoryStores` are for a test that must not
+ *   call a provider or stand up a database.
+ *
+ * ## Why the test runner is an optional peer
+ *
+ * The harnesses call `describe`/`it`/`expect` at module scope, so importing this pulls `vitest`. It is an
+ * **optional peer dependency**, not a dependency: a consumer who never imports this subpath never installs it,
+ * and nothing in a production bundle can reach it — the only paths to these modules are through this entry.
+ * `@electric-sql/pglite` is optional for the same reason, and only `pgliteExecutor` needs it.
+ */
+export * from "../testing/conformance/index.js";
+export * from "../testing/stub-model.js";
+export * from "../testing/memory-backend.js";
+export * from "../testing/pglite.js";
+export * from "../testing/conformance/audio.js";
+//# sourceMappingURL=testing.js.map

package/dist/graphql/resolvers.d.ts

@@ -5,7 +5,7 @@
  * shape and delegates to a service. No business logic lives in this layer.
  */
 import type { ExecutionContext } from "../core/context.js";
-import type { QuotaGuard } from "../usage/index.js";
+import type { QuotaGuard, RateLimitGuard } from "../usage/index.js";
 import type { UsageRollupStore } from "../persistence/index.js";
 import type { ConversationId, RunId } from "../core/ids.js";
 import type { ConversationStore, UsageStore } from "../persistence/index.js";
@@ -38,6 +38,8 @@ export type ResolverDeps = {
      * that blocks nothing is a bill the rollups make visible.
      */
     readonly quota?: QuotaGuard;
+    /** Capacity, as distinct from spend — task #248. Absent means unchecked. */
+    readonly rateLimit?: RateLimitGuard;
     /**
      * Rollups for the spend panel (#140).
      *

package/dist/graphql/resolvers.js

@@ -201,6 +201,20 @@ export const createResolvers = (deps) => {
                 //
                 // Optional, because a deployment with no limits configured is valid; when it is absent nothing is
                 // checked, which is the same as an unbounded limit.
+                /**
+                 * Rate before cost — task #248.
+                 *
+                 * This order is deliberate. A rate check is one atomic counter increment; a quota check reads a rollup.
+                 * A tenant hammering the platform should be turned away by the cheaper check, not made to do the more
+                 * expensive one first — otherwise the defence against a runaway client is itself proportional to how
+                 * hard the client is running.
+                 *
+                 * Optional like the quota, and absent means unchecked. See `createRateLimitGuard`: an absent policy or a
+                 * `max` of zero is unlimited, so adding this feature cannot refuse a deployment that has configured
+                 * nothing.
+                 */
+                if (deps.rateLimit !== undefined)
+                    await deps.rateLimit.assertAdmitted(ctx.execution);
                 if (deps.quota !== undefined)
                     await deps.quota.assertAdmitted(ctx.execution);
                 const started = await startOrEnqueueRun(deps.coordinator, { tenantId: tid(ctx), conversationId, runId });

package/dist/knowledge/communities.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Community detection — REQ-064 (#270), task #272.
+ *
+ * `graph-global` answers "what are the main themes?" by reducing over summaries of clusters. This produces the
+ * clusters.
+ *
+ * ## Why this is implemented here rather than imported
+ *
+ * `backend` has exactly two runtime dependencies, `ai` and `zod`, and that is a property worth keeping. But the
+ * dependency count is the smaller argument. The larger one is **determinism**: Microsoft's GraphRAG uses
+ * hierarchical Leiden, and the widely-used implementations of Leiden and Louvain are seeded-random — they
+ * shuffle node order to escape local optima, which is good for modularity and fatal here. #275 measures
+ * GraphRAG against a fixed baseline, #272's own incremental rebuild is verified by comparing against a
+ * previous clustering, and both need the same graph to cluster the same way twice.
+ *
+ * So this is Louvain with every source of nondeterminism removed:
+ *
+ * - Nodes are visited in **sorted id order**, never shuffled.
+ * - A tie in modularity gain is broken by the **smallest community id**, so equal options resolve the same way.
+ * - Aggregation preserves that ordering into the next level.
+ *
+ * The cost is some modularity — a shuffled Louvain finds slightly better partitions on average. That is a
+ * trade worth making for a result that can be measured, diffed and debugged, and it is stated here rather than
+ * discovered later by somebody wondering why two runs disagree.
+ *
+ * Louvain rather than label propagation, which was the other candidate: label propagation is simpler and
+ * roughly as fast, but it produces one flat partition and #272 needs **hierarchy**. Louvain's aggregation
+ * phases *are* the levels — level 0 is fine-grained, each subsequent level coarser — which is exactly the
+ * granularity choice `graph-global` has to make between "what are the main themes" and "what are the themes in
+ * observability".
+ */
+import type { TenantId } from "../core/ids.js";
+import type { GraphStore, KnowledgeRelationship, KnowledgeStore } from "../persistence/index.js";
+/** A cluster of entities at one level of the hierarchy. */
+export type Community = {
+    /**
+     * Deterministic and readable: `L<level>:<smallest member id>`.
+     *
+     * Derived from the membership rather than assigned by a counter, so the same cluster keeps the same id
+     * across runs — which is what lets a rebuild compare against the previous clustering at all. A counter would
+     * renumber everything whenever one entity moved.
+     */
+    readonly id: string;
+    readonly level: number;
+    /** Sorted. */
+    readonly entityIds: readonly string[];
+    /** Edges with both endpoints inside this community, sorted. */
+    readonly relationshipIds: readonly string[];
+    /** Chunks behind those entities and edges, sorted. The provenance a summary inherits. */
+    readonly chunkIds: readonly string[];
+    /**
+     * A fingerprint of exactly what this community contains.
+     *
+     * The mechanism behind incremental summarisation and visible staleness: a summary records the fingerprint it
+     * was written against, and a community whose fingerprint no longer matches is stale — knowable without
+     * re-reading the summary or trusting a timestamp.
+     */
+    readonly fingerprint: string;
+};
+/**
+ * How many levels of hierarchy to build.
+ *
+ * Two is the minimum AC-1 asks for and the useful default: level 0 is fine-grained clusters and level 1 groups
+ * them. More levels on a small graph collapse to the same partition repeated, which costs summarisation calls
+ * for no new information — so the loop stops early when a level stops merging anything.
+ */
+export declare const DEFAULT_COMMUNITY_LEVELS = 2;
+/**
+ * Cluster a graph into a hierarchy of communities.
+ *
+ * Pure and deterministic: the same entities and relationships always produce the same result, which every test
+ * of incremental rebuild depends on.
+ *
+ * Singletons are kept rather than dropped. An entity nothing links to is a real part of the corpus and a
+ * `graph-global` answer that silently omitted every unconnected concept would be quietly wrong about what the
+ * corpus contains.
+ */
+export declare const detectCommunities: (input: {
+    readonly entityIds: readonly string[];
+    readonly relationships: readonly KnowledgeRelationship[];
+    readonly chunksOf: (entityId: string) => readonly string[];
+    readonly levels?: number;
+}) => readonly Community[];
+/**
+ * Writes a community's summary — REQ-064 (#270), task #272.
+ *
+ * A port, like `EntityExtractor`, and optional for the same reason: a deployment that clusters but never runs
+ * `graph-global` needs no language model for it. Given the community's entities, its relationships and the
+ * text behind them, and asked for a short description of what this cluster is *about*.
+ */
+export interface CommunitySummariser {
+    readonly id: string;
+    summarise(input: {
+        readonly community: Community;
+        /** The chunk text behind the community, already permission-free — it is all one tenant's own material. */
+        readonly excerpts: readonly string[];
+        readonly entityNames: readonly string[];
+        readonly relationshipDescriptions: readonly string[];
+    }): Promise<{
+        readonly summary: string;
+        readonly usage?: {
+            readonly inputTokens?: number;
+            readonly outputTokens?: number;
+        };
+    }>;
+}
+export type CommunityRebuildResult = {
+    readonly communities: number;
+    readonly levels: number;
+    /** Communities whose summary was reused because their membership did not change. The incremental saving. */
+    readonly summariesKept: number;
+    readonly summariesWritten: number;
+    /** Summarisation calls that failed. The community survives without a summary — AC-7. */
+    readonly summariesFailed: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+};
+export type CommunityBuilderDeps = {
+    readonly store: GraphStore;
+    /** Absent means cluster but do not summarise. Useful, and the honest default for a deployment without `graph-global`. */
+    readonly summariser?: CommunitySummariser;
+    readonly knowledge?: KnowledgeStore;
+    readonly levels?: number;
+    /** Chunk excerpts handed to the summariser per community. A ceiling, because a community can span hundreds. */
+    readonly maxExcerpts?: number;
+    /**
+     * Which levels to summarise. Absent means all of them.
+     *
+     * **Worth setting, because summarising a level nobody queries is pure cost.** `graph-global` reads *one*
+     * level per query — the coarsest by default — and a two-level hierarchy over a real corpus has far more
+     * fine-grained communities than coarse ones. Summarising every level can therefore multiply the bill several
+     * times over for content no query will ever reduce across.
+     *
+     * Not defaulted to the coarsest, deliberately: a deployment that lets callers ask at a finer granularity
+     * needs those summaries, and silently not writing them would make `graph-global` at that level return
+     * nothing with no explanation. The cost is real either way; this makes it a decision.
+     */
+    readonly summariseLevels?: readonly number[];
+    readonly clock?: () => string;
+    readonly log?: (message: string, detail?: Readonly<Record<string, unknown>>) => void;
+};
+export declare const DEFAULT_MAX_EXCERPTS = 20;
+/**
+ * Rebuilds the community hierarchy, and re-summarises **only what changed**.
+ *
+ * This is where AC-5's "incremental" honestly lives, and it is worth being precise about the split rather than
+ * claiming more than is true:
+ *
+ * - **Clustering is global and cheap.** Community detection is global by nature — one entity moving can change
+ *   every level — so the whole graph is re-clustered. It is arithmetic over ids, with no model calls, and
+ *   pretending to do it incrementally would mean a partition that disagrees with itself.
+ * - **Summarisation is incremental and expensive.** One model call per community, and that is the cost worth
+ *   avoiding. A community whose membership fingerprint is unchanged keeps its summary untouched.
+ *
+ * So changing one source re-clusters everything and re-summarises the handful of communities that actually
+ * moved. The staleness window is therefore *zero for structure* and *one rebuild for summaries*, and a
+ * community caught between the two is visibly stale rather than silently wrong.
+ */
+export declare const createCommunityBuilder: (deps: CommunityBuilderDeps) => {
+    summariserId: string | null;
+    rebuild(context: {
+        readonly tenantId: TenantId;
+    }): Promise<CommunityRebuildResult>;
+};
+export type CommunityBuilder = ReturnType<typeof createCommunityBuilder>;
+//# sourceMappingURL=communities.d.ts.map