@slopus/happy-agent-base 0.0.0 → 0.0.2

package/dist/AgentConfig.js

@@ -0,0 +1,81 @@
+import { release } from "node:os";
+import { Type } from "@sinclair/typebox";
+import { createContextNamespace } from "@steve.kite/stdlib";
+/** The operating systems Node reports, mirroring `NodeJS.Platform`. */
+export const agentPlatformSchema = Type.Union([
+    Type.Literal("aix"),
+    Type.Literal("android"),
+    Type.Literal("cygwin"),
+    Type.Literal("darwin"),
+    Type.Literal("freebsd"),
+    Type.Literal("haiku"),
+    Type.Literal("linux"),
+    Type.Literal("netbsd"),
+    Type.Literal("openbsd"),
+    Type.Literal("sunos"),
+    Type.Literal("win32"),
+]);
+/**
+ * The settings one feature was configured with. The agent never looks inside: a feature owns
+ * the shape of its own entry and validates it against its own schema.
+ */
+export const agentFeatureConfigSchema = Type.Record(Type.String(), Type.Unknown());
+/**
+ * The machine an agent works on. It is all or nothing: an agent either knows its environment
+ * completely or not at all, so nothing it is told about the machine is ever half-true.
+ */
+export const agentEnvironmentSchema = Type.Object({
+    /** The operating system release, as a human-readable version string. */
+    osVersion: Type.String(),
+    /** The operating system the agent runs on. */
+    platform: agentPlatformSchema,
+    /** The absolute path the agent's work is rooted at. */
+    workingDirectory: Type.String(),
+    /** The shell the agent's commands run in, such as `/bin/zsh`. */
+    shell: Type.String(),
+});
+/**
+ * What an agent was created with: the environment it works on, when it has one, and one opaque
+ * settings map per feature, keyed by the feature's name. The configuration is static for the
+ * agent's whole life and is persisted when the agent is created, so a later process resolves
+ * the very same agent it was created as.
+ */
+export const agentConfigSchema = Type.Object({
+    /** The machine this agent was told it works on, when it was told anything at all. */
+    environment: Type.Optional(agentEnvironmentSchema),
+    /** Per-feature settings, keyed by feature name; each entry is opaque to the agent. */
+    features: Type.Optional(Type.Record(Type.String(), agentFeatureConfigSchema)),
+});
+/**
+ * The environment this process is running in, ready to be handed to an agent at creation. The
+ * platform is typed, so a Node release reporting an unknown platform fails to compile rather
+ * than slipping into a persisted configuration; an unset `SHELL` reports as no shell at all.
+ */
+export function currentAgentEnvironment() {
+    const platform = process.platform;
+    return {
+        osVersion: release(),
+        platform,
+        workingDirectory: process.cwd(),
+        shell: process.env.SHELL ?? "",
+    };
+}
+/** The context slot the agent's configuration is carried in, unset until an agent attaches one. */
+const configNamespace = createContextNamespace("happyAgentBase.agentConfig", undefined);
+/** Carry the configuration an agent was created with; every hook and tool reads it back. */
+export function withAgentConfig(ctx, config) {
+    return configNamespace.set(ctx, config);
+}
+/** The configuration of the agent owning this context, when one was attached. */
+export function agentConfig(ctx) {
+    return configNamespace.get(ctx);
+}
+/** The environment of the agent owning this context, when it was created with one. */
+export function agentEnvironment(ctx) {
+    return configNamespace.get(ctx)?.environment;
+}
+/** The opaque settings the named feature was configured with, if it was configured at all. */
+export function agentFeatureConfig(ctx, name) {
+    return configNamespace.get(ctx)?.features?.[name];
+}
+//# sourceMappingURL=AgentConfig.js.map

package/dist/AgentConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentConfig.js","sourceRoot":"","sources":["../sources/AgentConfig.ts"],"names":[],"mappings":"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"}

package/dist/AgentContexts.d.ts

@@ -0,0 +1,40 @@
+import type { SessionReasoningEffort, SessionServiceTier } from "@slopus/happy-providers";
+import { type Context } from "@steve.kite/stdlib";
+import type { AgentKV } from "./AgentKV.js";
+/**
+ * Derive the agent's context carrying its ID, provider ID, model, effort, and service tier — all
+ * serializable values. The agent applies this once at construction, so hooks and tool executions
+ * can read the values back through the accessors below. The ID is what lets one feature instance
+ * serve every agent in a collection: a shared feature learns which agent a hook is running for
+ * from the context rather than from something it was constructed with.
+ */
+export declare function withAgentContext(ctx: Context, values: {
+    readonly id: string;
+    readonly provider: string;
+    readonly model?: string | undefined;
+    readonly effort?: SessionReasoningEffort | undefined;
+    readonly serviceTier?: SessionServiceTier | undefined;
+}): Context;
+/** The ID of the agent owning this context. */
+export declare function agentId(ctx: Context): string | undefined;
+/** The model configured for the agent owning this context, when one was set. */
+export declare function agentModel(ctx: Context): string | undefined;
+/** The reasoning effort configured for the agent owning this context, when one was set. */
+export declare function agentEffort(ctx: Context): SessionReasoningEffort | undefined;
+/** The registry ID of the provider of the agent owning this context. */
+export declare function agentProvider(ctx: Context): string | undefined;
+/** The service tier configured for the agent owning this context, when one was set. */
+export declare function agentServiceTier(ctx: Context): SessionServiceTier | undefined;
+/** Carry a scoped key-value store on the context, replacing any store carried before. */
+export declare function withAgentKV(ctx: Context, kv: AgentKV): Context;
+/** The scoped key-value store carried on this context, when the agent attached one. */
+export declare function agentKV(ctx: Context): AgentKV | undefined;
+/**
+ * Carry the store belonging to the run in progress, replacing any run store carried before. What
+ * it holds lives exactly as long as the work does: the agent erases the whole scope in the
+ * transaction that settles it, so nothing written here outlives the run that wrote it.
+ */
+export declare function withAgentRunKV(ctx: Context, kv: AgentKV): Context;
+/** The run's own store carried on this context, when the agent attached one. */
+export declare function agentRunKV(ctx: Context): AgentKV | undefined;
+//# sourceMappingURL=AgentContexts.d.ts.map

package/dist/AgentContexts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentContexts.d.ts","sourceRoot":"","sources":["../sources/AgentContexts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC1F,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE1E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAuB5C;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC5B,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE;IACJ,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;CACzD,GACF,OAAO,CAMT;AAED,+CAA+C;AAC/C,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAExD;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE3D;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,sBAAsB,GAAG,SAAS,CAE5E;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE9D;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAE7E;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,OAAO,CAE9D;AAED,uFAAuF;AACvF,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,OAAO,CAEjE;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAE5D"}

package/dist/AgentContexts.js

@@ -0,0 +1,70 @@
+import { createContextNamespace } from "@steve.kite/stdlib";
+/** Backing storage for `agentId`: the ID of the agent owning a context. */
+const idNamespace = createContextNamespace("agentId", undefined);
+/** Backing storage for `agentModel`: the model configured for the agent, when one was set. */
+const modelNamespace = createContextNamespace("agentModel", undefined);
+/** Backing storage for `agentEffort`: the reasoning effort configured, when one was set. */
+const effortNamespace = createContextNamespace("agentEffort", undefined);
+/** Backing storage for `agentProvider`: the registry ID of the provider owning a context. */
+const providerNamespace = createContextNamespace("agentProvider", undefined);
+/** Backing storage for `agentServiceTier`: the service tier configured, when one was set. */
+const serviceTierNamespace = createContextNamespace("agentServiceTier", undefined);
+/** Backing storage for `agentKV`: the scoped key-value store carried on a context. */
+const kvNamespace = createContextNamespace("agentKV", undefined);
+/** Backing storage for `agentRunKV`: the run's own store, erased when the agent settles. */
+const runKVNamespace = createContextNamespace("agentRunKV", undefined);
+/**
+ * Derive the agent's context carrying its ID, provider ID, model, effort, and service tier — all
+ * serializable values. The agent applies this once at construction, so hooks and tool executions
+ * can read the values back through the accessors below. The ID is what lets one feature instance
+ * serve every agent in a collection: a shared feature learns which agent a hook is running for
+ * from the context rather than from something it was constructed with.
+ */
+export function withAgentContext(ctx, values) {
+    const withId = idNamespace.set(ctx, values.id);
+    const withProvider = providerNamespace.set(withId, values.provider);
+    const withModel = modelNamespace.set(withProvider, values.model);
+    const withEffort = effortNamespace.set(withModel, values.effort);
+    return serviceTierNamespace.set(withEffort, values.serviceTier);
+}
+/** The ID of the agent owning this context. */
+export function agentId(ctx) {
+    return idNamespace.get(ctx);
+}
+/** The model configured for the agent owning this context, when one was set. */
+export function agentModel(ctx) {
+    return modelNamespace.get(ctx);
+}
+/** The reasoning effort configured for the agent owning this context, when one was set. */
+export function agentEffort(ctx) {
+    return effortNamespace.get(ctx);
+}
+/** The registry ID of the provider of the agent owning this context. */
+export function agentProvider(ctx) {
+    return providerNamespace.get(ctx);
+}
+/** The service tier configured for the agent owning this context, when one was set. */
+export function agentServiceTier(ctx) {
+    return serviceTierNamespace.get(ctx);
+}
+/** Carry a scoped key-value store on the context, replacing any store carried before. */
+export function withAgentKV(ctx, kv) {
+    return kvNamespace.set(ctx, kv);
+}
+/** The scoped key-value store carried on this context, when the agent attached one. */
+export function agentKV(ctx) {
+    return kvNamespace.get(ctx);
+}
+/**
+ * Carry the store belonging to the run in progress, replacing any run store carried before. What
+ * it holds lives exactly as long as the work does: the agent erases the whole scope in the
+ * transaction that settles it, so nothing written here outlives the run that wrote it.
+ */
+export function withAgentRunKV(ctx, kv) {
+    return runKVNamespace.set(ctx, kv);
+}
+/** The run's own store carried on this context, when the agent attached one. */
+export function agentRunKV(ctx) {
+    return runKVNamespace.get(ctx);
+}
+//# sourceMappingURL=AgentContexts.js.map

package/dist/AgentContexts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentContexts.js","sourceRoot":"","sources":["../sources/AgentContexts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAgB,MAAM,oBAAoB,CAAC;AAI1E,2EAA2E;AAC3E,MAAM,WAAW,GAAG,sBAAsB,CAAqB,SAAS,EAAE,SAAS,CAAC,CAAC;AACrF,8FAA8F;AAC9F,MAAM,cAAc,GAAG,sBAAsB,CAAqB,YAAY,EAAE,SAAS,CAAC,CAAC;AAC3F,4FAA4F;AAC5F,MAAM,eAAe,GAAG,sBAAsB,CAC1C,aAAa,EACb,SAAS,CACZ,CAAC;AACF,6FAA6F;AAC7F,MAAM,iBAAiB,GAAG,sBAAsB,CAAqB,eAAe,EAAE,SAAS,CAAC,CAAC;AACjG,6FAA6F;AAC7F,MAAM,oBAAoB,GAAG,sBAAsB,CAC/C,kBAAkB,EAClB,SAAS,CACZ,CAAC;AACF,sFAAsF;AACtF,MAAM,WAAW,GAAG,sBAAsB,CAAsB,SAAS,EAAE,SAAS,CAAC,CAAC;AACtF,4FAA4F;AAC5F,MAAM,cAAc,GAAG,sBAAsB,CAAsB,YAAY,EAAE,SAAS,CAAC,CAAC;AAE5F;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC5B,GAAY,EACZ,MAMC;IAED,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,iBAAiB,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpE,MAAM,SAAS,GAAG,cAAc,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IACjE,MAAM,UAAU,GAAG,eAAe,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACjE,OAAO,oBAAoB,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;AACpE,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,OAAO,CAAC,GAAY;IAChC,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,UAAU,CAAC,GAAY;IACnC,OAAO,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,WAAW,CAAC,GAAY;IACpC,OAAO,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,aAAa,CAAC,GAAY;IACtC,OAAO,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACtC,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,gBAAgB,CAAC,GAAY;IACzC,OAAO,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,WAAW,CAAC,GAAY,EAAE,EAAW;IACjD,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACpC,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,OAAO,CAAC,GAAY;IAChC,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY,EAAE,EAAW;IACpD,OAAO,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,UAAU,CAAC,GAAY;IACnC,OAAO,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC"}

package/dist/AgentFeature.d.ts

@@ -0,0 +1,119 @@
+import type { ProviderModelCompatibilityType, SessionEvent, SessionReasoningEffort, SessionServiceTier, SessionSystemMessage } from "@slopus/happy-providers";
+import type { Context } from "@steve.kite/stdlib";
+import type { AgentBaseInference, AgentBaseModelChange, AgentBaseToolExecution, AgentBaseTurn, AgentBaseTurnStart, MaybePromise } from "./AgentBaseHooks.js";
+import type { AgentFeatureAction } from "./AgentFeatureAction.js";
+import type { AgentKV } from "./AgentKV.js";
+import type { AnyAgentTool } from "./AgentTool.js";
+/**
+ * The agent a hook is serving, in full. One feature instance serves every agent in a collection,
+ * so this — rather than anything the feature was constructed with — is what tells it whose turn
+ * it is looking at, and what that agent is about to run on.
+ */
+export interface AgentFeatureAgent {
+    /** The system-generated identity of the agent, stable for its whole life. */
+    readonly id: string;
+    /** The registry ID of the provider in force, which one agent may switch between. */
+    readonly provider: string;
+    /**
+     * What kind of provider that ID is registered as — `"claude"`, `"codex"`, and so on. It is
+     * the vendor shape a feature has to reason about when a provider ID alone says nothing, and
+     * is absent when the ID is not registered.
+     */
+    readonly providerKind: ProviderModelCompatibilityType | undefined;
+    /** The model in force, absent when none was ever selected. */
+    readonly model: string | undefined;
+    /** The reasoning effort in force, absent when none was ever selected. */
+    readonly effort: SessionReasoningEffort | undefined;
+    /** The service tier in force, absent when none was ever selected. */
+    readonly tier: SessionServiceTier | undefined;
+}
+/**
+ * What every hook of a feature is handed alongside the context: which agent it is running for,
+ * and the three stores it may write to, each with its own lifetime.
+ *
+ * They are passed rather than read off the context because a feature's own dependencies are not
+ * ambient state to be looked up: a hook is given exactly what it is entitled to, and cannot be
+ * handed a context that quietly means a different agent.
+ */
+export interface AgentFeatureScope {
+    /** The agent this hook is running for, and the selection it is running on. */
+    readonly agent: AgentFeatureAgent;
+    /**
+     * The feature's durable store for this one agent, scoped to `feature.<name>`. It belongs to
+     * the agent's conversation: it outlives every run, and it is cleared when the identity is
+     * created again. Renaming a feature orphans everything it stored here.
+     */
+    readonly kv: AgentKV;
+    /**
+     * The feature's durable store shared by every agent in the collection, and outliving all of
+     * them. Work one agent owes another lives here, since an agent's own store belongs to its
+     * conversation alone.
+     */
+    readonly sharedKV: AgentKV;
+    /**
+     * The feature's store for the run in progress, erased in the transaction that settles the
+     * agent. It is where a feature keeps what only makes sense while the agent is working, so a
+     * crash mid-run leaves notes a resumed run can read, and a finished run leaves none at all.
+     */
+    readonly runKV: AgentKV;
+}
+/**
+ * One independent capability of an `Agent`: a feature implements any subset of the agent hooks,
+ * and the agent merges every feature's implementations into the singular hooks its internal
+ * `AgentBase` runs with. The hook contracts are the same as `AgentBaseHooks`; see there for
+ * when each hook fires and what its return value means.
+ *
+ * Every hook receives the agent's context first and its own `AgentFeatureScope` second.
+ */
+export interface AgentFeature<Tool extends AnyAgentTool = AnyAgentTool> {
+    /**
+     * A stable identifier for the feature. Its persisted key-value entries live under this
+     * name, so renaming a feature orphans everything it stored.
+     */
+    readonly name: string;
+    /** Observes every session event; must never fail or delay the run. */
+    readonly onEvent?: (ctx: Context, scope: AgentFeatureScope, event: SessionEvent) => void;
+    /** Merged after the base state and every earlier feature's instructions, in feature order. */
+    readonly instructions?: (ctx: Context, scope: AgentFeatureScope) => MaybePromise<string>;
+    /** Merged after the base state and every earlier feature's tools, in feature order. */
+    readonly tools?: (ctx: Context, scope: AgentFeatureScope) => MaybePromise<readonly Tool[]>;
+    /**
+     * Wraps validated tool execution. Features compose as nested middleware in array order.
+     * See `AgentBaseHooks.aroundToolExecution` for the continuation contract.
+     */
+    readonly aroundToolExecution?: (ctx: Context, scope: AgentFeatureScope, execution: AgentBaseToolExecution) => MaybePromise<unknown>;
+    /** The first feature that returns a handoff message wins the reset injection. */
+    readonly modelChanged?: (ctx: Context, scope: AgentFeatureScope, change: AgentBaseModelChange) => MaybePromise<SessionSystemMessage | undefined>;
+    /** Called when the loop leaves the settled state and begins working. */
+    readonly beforeAgentLoop?: (ctx: Context, scope: AgentFeatureScope) => MaybePromise<void>;
+    /**
+     * Receives the measured size of the context the turn is about to run on. Actions from every
+     * feature are concatenated and applied before the turn's first inference.
+     */
+    readonly beforeTurn?: (ctx: Context, scope: AgentFeatureScope, turn: AgentBaseTurnStart) => MaybePromise<readonly AgentFeatureAction[] | undefined>;
+    /** Called immediately before each inference request. */
+    readonly beforeInference?: (ctx: Context, scope: AgentFeatureScope) => MaybePromise<void>;
+    /** Receives how the response ended and the token counts the provider measured for it. */
+    readonly afterInference?: (ctx: Context, scope: AgentFeatureScope, inference: AgentBaseInference) => MaybePromise<void>;
+    /**
+     * Receives the token counts the turn's last measured response reported. Actions from every
+     * feature are concatenated and applied together.
+     */
+    readonly afterTurn?: (ctx: Context, scope: AgentFeatureScope, turn: AgentBaseTurn) => MaybePromise<readonly AgentFeatureAction[] | undefined>;
+    /** Actions from every feature are concatenated and applied together. */
+    readonly afterAgentLoop?: (ctx: Context, scope: AgentFeatureScope) => MaybePromise<readonly AgentFeatureAction[] | undefined>;
+    /**
+     * Called inside the transaction that records the agent as settled. The feature's stores write
+     * into that transaction, so what a feature concludes about the run and the fact that the run
+     * is over become durable together. The `Transact` suffix is what marks a hook as running
+     * inside a transaction. The run store is erased by that same transaction, so this is the last
+     * chance to keep any part of what the run wrote about itself.
+     *
+     * Unlike the observing hooks, a failure here is not contained: it rolls the settlement back
+     * along with everything every feature wrote, and the agent stays recorded as working.
+     */
+    readonly afterAgentSettledTransact?: (ctx: Context, scope: AgentFeatureScope) => MaybePromise<void>;
+    /** Called once after the loop has fully settled and no feature reopened it. */
+    readonly afterAgentSettled?: (ctx: Context, scope: AgentFeatureScope) => MaybePromise<void>;
+}
+//# sourceMappingURL=AgentFeature.d.ts.map

package/dist/AgentFeature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentFeature.d.ts","sourceRoot":"","sources":["../sources/AgentFeature.ts"],"names":[],"mappings":"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"}

package/dist/AgentFeature.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=AgentFeature.js.map

package/dist/AgentFeature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentFeature.js","sourceRoot":"","sources":["../sources/AgentFeature.ts"],"names":[],"mappings":""}

package/dist/AgentFeatureAction.d.ts

@@ -0,0 +1,16 @@
+import type { SessionUserMessage } from "@slopus/happy-providers";
+/**
+ * What a lifecycle hook can ask the agent to do next: queue a steering or sent message through
+ * the ordinary durable queues, or trigger a compaction. An action drives the loop exactly like
+ * an external call to `steer`, `send`, or `compact` would.
+ */
+export type AgentFeatureAction = {
+    readonly type: "steer";
+    readonly message: SessionUserMessage;
+} | {
+    readonly type: "send";
+    readonly message: SessionUserMessage;
+} | {
+    readonly type: "compact";
+};
+//# sourceMappingURL=AgentFeatureAction.d.ts.map

package/dist/AgentFeatureAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentFeatureAction.d.ts","sourceRoot":"","sources":["../sources/AgentFeatureAction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC"}

package/dist/AgentFeatureAction.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=AgentFeatureAction.js.map

package/dist/AgentFeatureAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentFeatureAction.js","sourceRoot":"","sources":["../sources/AgentFeatureAction.ts"],"names":[],"mappings":""}

package/dist/AgentKV.d.ts

@@ -0,0 +1,63 @@
+import { type Context } from "@steve.kite/stdlib";
+import type { AgentPersistence } from "./AgentPersistence.js";
+/**
+ * A key-value store scoped under one prefix of the agent's sorted store. The agent carries a
+ * session-scoped instance on its context, and narrows it for each caller: a feature works
+ * under its own name, a tool execution under its call ID. Keys are always relative to the
+ * scope — a holder can neither see nor touch anything outside it. Segments join with `.`.
+ *
+ * The object is nothing but a scope: every operation runs on the context it is given, so which
+ * transaction a write joins and how long the handle stays usable are both decided by that
+ * context and never by the handle.
+ */
+export declare class AgentKV {
+    #private;
+    /** The absolute key prefix of this scope, ending with the separator. */
+    readonly prefix: string;
+    /** Build a scope over `prefix` of `persistence`. */
+    constructor(persistence: AgentPersistence, prefix: string);
+    /**
+     * A narrower store under `segments` within this scope. Each segment is exactly one level:
+     * a dot inside a segment is escaped, so the scope `alpha.beta` cannot be reached through
+     * the scope `alpha` under the relative key `beta.…`, and two scopes stay distinct whenever
+     * their segment lists differ.
+     */
+    scoped(...segments: readonly string[]): AgentKV;
+    /** The stored value, or undefined when the key is absent. */
+    read(ctx: Context, key: string): Promise<unknown>;
+    /** Every entry under the scope — or under `prefix` within it — with scope-relative keys. */
+    list(ctx: Context, prefix?: string): Promise<readonly {
+        readonly key: string;
+        readonly value: unknown;
+    }[]>;
+    /** Store the value under `key`, replacing whatever was there before. */
+    write(ctx: Context, key: string, value: unknown): Promise<void>;
+    /**
+     * Read, decide, and write, so the value the updater sees is exactly the value it replaces.
+     * One store has one owner, so nothing else can write between the read and the write. An
+     * updater that throws leaves the stored value untouched.
+     */
+    update<Value>(ctx: Context, key: string, updater: (current: unknown) => Value | Promise<Value>): Promise<Value>;
+    /**
+     * Run work as one atomic step of the underlying store: everything it writes commits together,
+     * and a thrown error leaves the store exactly as it was. The work is given this same scope and
+     * the transaction's context, whose lifetime ends when the work returns, so a transaction
+     * cannot be written into after it has committed.
+     */
+    transaction<Result>(ctx: Context, work: (kv: AgentKV, txCtx: Context) => Promise<Result>): Promise<Result>;
+    /**
+     * Claim a key: writes only when it is absent, and answers whether this caller claimed it.
+     * Two callers racing for one key cannot both be told they wrote it.
+     */
+    writeIfAbsent(ctx: Context, key: string, value: unknown): Promise<boolean>;
+    /**
+     * Remove every entry in this scope, including the ones its narrower scopes wrote. This is how
+     * a store whose lifetime has ended is disposed of — the run store when the agent settles — so
+     * it runs as one operation of the underlying store and joins a transaction like any other
+     * write.
+     */
+    clear(ctx: Context): Promise<void>;
+    /** Remove the entry stored under `key`, if any. */
+    delete(ctx: Context, key: string): Promise<void>;
+}
+//# sourceMappingURL=AgentKV.d.ts.map

package/dist/AgentKV.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentKV.d.ts","sourceRoot":"","sources":["../sources/AgentKV.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAEhE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAe9D;;;;;;;;;GASG;AACH,qBAAa,OAAO;;IAChB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAKxB,oDAAoD;IACpD,YAAY,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAGxD;IAED;;;;;OAKG;IACH,MAAM,CAAC,GAAG,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAK9C;IAED,6DAA6D;IACvD,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKtD;IAED,4FAA4F;IACtF,IAAI,CACN,GAAG,EAAE,OAAO,EACZ,MAAM,SAAK,GACZ,OAAO,CAAC,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC,CAIvE;IAED,wEAAwE;IAClE,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAGpE;IAED;;;;OAIG;IACG,MAAM,CAAC,KAAK,EACd,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GACtD,OAAO,CAAC,KAAK,CAAC,CAQhB;IAED;;;;;OAKG;IACG,WAAW,CAAC,MAAM,EACpB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,GACvD,OAAO,CAAC,MAAM,CAAC,CAWjB;IAED;;;OAGG;IACG,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAG/E;IAED;;;;;OAKG;IACG,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvC;IAED,mDAAmD;IAC7C,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrD;CACJ"}

package/dist/AgentKV.js

@@ -0,0 +1,122 @@
+import { withLifetime } from "@steve.kite/stdlib";
+/**
+ * Refuse a store operation whose context has already ended. What a holder of a store may do is
+ * decided by the context it is given rather than by the object: a store used inside a transaction,
+ * or handed to a tool for the length of its turn, keeps working exactly as long as that work
+ * does. Using it afterwards is a mistake in the caller, and says so instead of quietly writing
+ * into a transaction that has committed or a turn that was cancelled.
+ */
+function assertLive(ctx) {
+    if (ctx.lifetime?.aborted === true) {
+        throw new Error("The store cannot be used: the work its context belongs to has ended.");
+    }
+}
+/**
+ * A key-value store scoped under one prefix of the agent's sorted store. The agent carries a
+ * session-scoped instance on its context, and narrows it for each caller: a feature works
+ * under its own name, a tool execution under its call ID. Keys are always relative to the
+ * scope — a holder can neither see nor touch anything outside it. Segments join with `.`.
+ *
+ * The object is nothing but a scope: every operation runs on the context it is given, so which
+ * transaction a write joins and how long the handle stays usable are both decided by that
+ * context and never by the handle.
+ */
+export class AgentKV {
+    /** The absolute key prefix of this scope, ending with the separator. */
+    prefix;
+    /** The append-only store this scope reads and writes through. */
+    #persistence;
+    /** Build a scope over `prefix` of `persistence`. */
+    constructor(persistence, prefix) {
+        this.#persistence = persistence;
+        this.prefix = prefix;
+    }
+    /**
+     * A narrower store under `segments` within this scope. Each segment is exactly one level:
+     * a dot inside a segment is escaped, so the scope `alpha.beta` cannot be reached through
+     * the scope `alpha` under the relative key `beta.…`, and two scopes stay distinct whenever
+     * their segment lists differ.
+     */
+    scoped(...segments) {
+        const escaped = segments.map((segment) => segment.replaceAll("%", "%25").replaceAll(".", "%2E"));
+        return new AgentKV(this.#persistence, `${this.prefix}${escaped.join(".")}.`);
+    }
+    /** The stored value, or undefined when the key is absent. */
+    async read(ctx, key) {
+        assertLive(ctx);
+        const full = `${this.prefix}${key}`;
+        const entries = await this.#persistence.readValues(ctx, full);
+        return entries.find((entry) => entry.key === full)?.value;
+    }
+    /** Every entry under the scope — or under `prefix` within it — with scope-relative keys. */
+    async list(ctx, prefix = "") {
+        assertLive(ctx);
+        const entries = await this.#persistence.readValues(ctx, `${this.prefix}${prefix}`);
+        return entries.map(({ key, value }) => ({ key: key.slice(this.prefix.length), value }));
+    }
+    /** Store the value under `key`, replacing whatever was there before. */
+    async write(ctx, key, value) {
+        assertLive(ctx);
+        await this.#persistence.writeValue(ctx, `${this.prefix}${key}`, value);
+    }
+    /**
+     * Read, decide, and write, so the value the updater sees is exactly the value it replaces.
+     * One store has one owner, so nothing else can write between the read and the write. An
+     * updater that throws leaves the stored value untouched.
+     */
+    async update(ctx, key, updater) {
+        assertLive(ctx);
+        const full = `${this.prefix}${key}`;
+        const entries = await this.#persistence.readValues(ctx, full);
+        const current = entries.find((entry) => entry.key === full)?.value;
+        const next = await updater(current);
+        await this.#persistence.writeValue(ctx, full, next);
+        return next;
+    }
+    /**
+     * Run work as one atomic step of the underlying store: everything it writes commits together,
+     * and a thrown error leaves the store exactly as it was. The work is given this same scope and
+     * the transaction's context, whose lifetime ends when the work returns, so a transaction
+     * cannot be written into after it has committed.
+     */
+    async transaction(ctx, work) {
+        assertLive(ctx);
+        return await this.#persistence.transaction(ctx, async (txCtx) => {
+            const committed = new AbortController();
+            const liveCtx = withLifetime(txCtx, committed.signal);
+            try {
+                return await work(this, liveCtx);
+            }
+            finally {
+                committed.abort();
+            }
+        });
+    }
+    /**
+     * Claim a key: writes only when it is absent, and answers whether this caller claimed it.
+     * Two callers racing for one key cannot both be told they wrote it.
+     */
+    async writeIfAbsent(ctx, key, value) {
+        assertLive(ctx);
+        return await this.#persistence.writeValueIfAbsent(ctx, `${this.prefix}${key}`, value);
+    }
+    /**
+     * Remove every entry in this scope, including the ones its narrower scopes wrote. This is how
+     * a store whose lifetime has ended is disposed of — the run store when the agent settles — so
+     * it runs as one operation of the underlying store and joins a transaction like any other
+     * write.
+     */
+    async clear(ctx) {
+        assertLive(ctx);
+        const entries = await this.#persistence.readValues(ctx, this.prefix);
+        for (const entry of entries) {
+            await this.#persistence.deleteValue(ctx, entry.key);
+        }
+    }
+    /** Remove the entry stored under `key`, if any. */
+    async delete(ctx, key) {
+        assertLive(ctx);
+        await this.#persistence.deleteValue(ctx, `${this.prefix}${key}`);
+    }
+}
+//# sourceMappingURL=AgentKV.js.map

package/dist/AgentKV.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentKV.js","sourceRoot":"","sources":["../sources/AgentKV.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAgB,MAAM,oBAAoB,CAAC;AAIhE;;;;;;GAMG;AACH,SAAS,UAAU,CAAC,GAAY;IAC5B,IAAI,GAAG,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;IAC5F,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,OAAO;IAChB,wEAAwE;IAC/D,MAAM,CAAS;IAExB,iEAAiE;IACxD,YAAY,CAAmB;IAExC,oDAAoD;IACpD,YAAY,WAA6B,EAAE,MAAc;QACrD,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,GAAG,QAA2B;QACjC,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACrC,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CACxD,CAAC;QACF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjF,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,IAAI,CAAC,GAAY,EAAE,GAAW;QAChC,UAAU,CAAC,GAAG,CAAC,CAAC;QAChB,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC9D,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,EAAE,KAAK,CAAC;IAC9D,CAAC;IAED,4FAA4F;IAC5F,KAAK,CAAC,IAAI,CACN,GAAY,EACZ,MAAM,GAAG,EAAE;QAEX,UAAU,CAAC,GAAG,CAAC,CAAC;QAChB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;QACnF,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAC5F,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,KAAK,CAAC,GAAY,EAAE,GAAW,EAAE,KAAc;QACjD,UAAU,CAAC,GAAG,CAAC,CAAC;QAChB,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC;IAC3E,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,CACR,GAAY,EACZ,GAAW,EACX,OAAqD;QAErD,UAAU,CAAC,GAAG,CAAC,CAAC;QAChB,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC9D,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,EAAE,KAAK,CAAC;QACnE,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;QACpC,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,WAAW,CACb,GAAY,EACZ,IAAsD;QAEtD,UAAU,CAAC,GAAG,CAAC,CAAC;QAChB,OAAO,MAAM,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YAC5D,MAAM,SAAS,GAAG,IAAI,eAAe,EAAE,CAAC;YACxC,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;YACtD,IAAI,CAAC;gBACD,OAAO,MAAM,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YACrC,CAAC;oBAAS,CAAC;gBACP,SAAS,CAAC,KAAK,EAAE,CAAC;YACtB,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,aAAa,CAAC,GAAY,EAAE,GAAW,EAAE,KAAc;QACzD,UAAU,CAAC,GAAG,CAAC,CAAC;QAChB,OAAO,MAAM,IAAI,CAAC,YAAY,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC;IAC1F,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK,CAAC,GAAY;QACpB,UAAU,CAAC,GAAG,CAAC,CAAC;QAChB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACrE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC1B,MAAM,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QACxD,CAAC;IACL,CAAC;IAED,mDAAmD;IACnD,KAAK,CAAC,MAAM,CAAC,GAAY,EAAE,GAAW;QAClC,UAAU,CAAC,GAAG,CAAC,CAAC;QAChB,MAAM,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,CAAC;IACrE,CAAC;CACJ"}

package/dist/AgentModel.d.ts

@@ -0,0 +1,17 @@
+import type { SessionReasoningEffort, SessionServiceTier } from "@slopus/happy-providers";
+/** One provider/model route available to agents and subagents. */
+export interface AgentModel {
+    /** The registry ID of the provider this route is served through. */
+    readonly providerId: string;
+    /** The model identifier as the provider knows it. */
+    readonly id: string;
+    /** Human-readable label shown in the model picker. */
+    readonly name: string;
+    /** Reasoning efforts this model accepts, in picker order. */
+    readonly effortLevels: readonly SessionReasoningEffort[];
+    /** The effort used when nothing more specific was requested. */
+    readonly defaultEffort: SessionReasoningEffort;
+    /** Service tiers this model accepts, when the provider offers a choice. */
+    readonly serviceTiers?: readonly SessionServiceTier[];
+}
+//# sourceMappingURL=AgentModel.d.ts.map

package/dist/AgentModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentModel.d.ts","sourceRoot":"","sources":["../sources/AgentModel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE1F,kEAAkE;AAClE,MAAM,WAAW,UAAU;IACvB,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACzD,gEAAgE;IAChE,QAAQ,CAAC,aAAa,EAAE,sBAAsB,CAAC;IAC/C,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACzD"}

package/dist/AgentModel.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=AgentModel.js.map

package/dist/AgentModel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentModel.js","sourceRoot":"","sources":["../sources/AgentModel.ts"],"names":[],"mappings":""}