@slopus/happy-agent-base 0.0.0 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +640 -15
  3. package/dist/Agent.d.ts +86 -0
  4. package/dist/Agent.d.ts.map +1 -0
  5. package/dist/Agent.js +326 -0
  6. package/dist/Agent.js.map +1 -0
  7. package/dist/AgentBase.d.ts +340 -0
  8. package/dist/AgentBase.d.ts.map +1 -0
  9. package/dist/AgentBase.js +2295 -0
  10. package/dist/AgentBase.js.map +1 -0
  11. package/dist/AgentBaseHooks.d.ts +156 -0
  12. package/dist/AgentBaseHooks.d.ts.map +1 -0
  13. package/dist/AgentBaseHooks.js +2 -0
  14. package/dist/AgentBaseHooks.js.map +1 -0
  15. package/dist/AgentBasePending.d.ts +49 -0
  16. package/dist/AgentBasePending.d.ts.map +1 -0
  17. package/dist/AgentBasePending.js +73 -0
  18. package/dist/AgentBasePending.js.map +1 -0
  19. package/dist/AgentBaseState.d.ts +13 -0
  20. package/dist/AgentBaseState.d.ts.map +1 -0
  21. package/dist/AgentBaseState.js +2 -0
  22. package/dist/AgentBaseState.js.map +1 -0
  23. package/dist/AgentBaseStoreLock.d.ts +16 -0
  24. package/dist/AgentBaseStoreLock.d.ts.map +1 -0
  25. package/dist/AgentBaseStoreLock.js +37 -0
  26. package/dist/AgentBaseStoreLock.js.map +1 -0
  27. package/dist/AgentConfig.d.ts +67 -0
  28. package/dist/AgentConfig.d.ts.map +1 -0
  29. package/dist/AgentConfig.js +81 -0
  30. package/dist/AgentConfig.js.map +1 -0
  31. package/dist/AgentContexts.d.ts +40 -0
  32. package/dist/AgentContexts.d.ts.map +1 -0
  33. package/dist/AgentContexts.js +70 -0
  34. package/dist/AgentContexts.js.map +1 -0
  35. package/dist/AgentFeature.d.ts +119 -0
  36. package/dist/AgentFeature.d.ts.map +1 -0
  37. package/dist/AgentFeature.js +2 -0
  38. package/dist/AgentFeature.js.map +1 -0
  39. package/dist/AgentFeatureAction.d.ts +16 -0
  40. package/dist/AgentFeatureAction.d.ts.map +1 -0
  41. package/dist/AgentFeatureAction.js +2 -0
  42. package/dist/AgentFeatureAction.js.map +1 -0
  43. package/dist/AgentKV.d.ts +63 -0
  44. package/dist/AgentKV.d.ts.map +1 -0
  45. package/dist/AgentKV.js +122 -0
  46. package/dist/AgentKV.js.map +1 -0
  47. package/dist/AgentModel.d.ts +17 -0
  48. package/dist/AgentModel.d.ts.map +1 -0
  49. package/dist/AgentModel.js +2 -0
  50. package/dist/AgentModel.js.map +1 -0
  51. package/dist/AgentPersistence.d.ts +95 -0
  52. package/dist/AgentPersistence.d.ts.map +1 -0
  53. package/dist/AgentPersistence.js +2 -0
  54. package/dist/AgentPersistence.js.map +1 -0
  55. package/dist/AgentProviders.d.ts +22 -0
  56. package/dist/AgentProviders.d.ts.map +1 -0
  57. package/dist/AgentProviders.js +35 -0
  58. package/dist/AgentProviders.js.map +1 -0
  59. package/dist/AgentRef.d.ts +41 -0
  60. package/dist/AgentRef.d.ts.map +1 -0
  61. package/dist/AgentRef.js +60 -0
  62. package/dist/AgentRef.js.map +1 -0
  63. package/dist/AgentStorage.d.ts +19 -0
  64. package/dist/AgentStorage.d.ts.map +1 -0
  65. package/dist/AgentStorage.js +16 -0
  66. package/dist/AgentStorage.js.map +1 -0
  67. package/dist/AgentSystem.d.ts +50 -0
  68. package/dist/AgentSystem.d.ts.map +1 -0
  69. package/dist/AgentSystem.js +2 -0
  70. package/dist/AgentSystem.js.map +1 -0
  71. package/dist/AgentSystemContext.d.ts +15 -0
  72. package/dist/AgentSystemContext.d.ts.map +1 -0
  73. package/dist/AgentSystemContext.js +20 -0
  74. package/dist/AgentSystemContext.js.map +1 -0
  75. package/dist/AgentSystemLocal.d.ts +103 -0
  76. package/dist/AgentSystemLocal.d.ts.map +1 -0
  77. package/dist/AgentSystemLocal.js +282 -0
  78. package/dist/AgentSystemLocal.js.map +1 -0
  79. package/dist/AgentSystemRef.d.ts +56 -0
  80. package/dist/AgentSystemRef.d.ts.map +1 -0
  81. package/dist/AgentSystemRef.js +75 -0
  82. package/dist/AgentSystemRef.js.map +1 -0
  83. package/dist/AgentTaskContext.d.ts +17 -0
  84. package/dist/AgentTaskContext.d.ts.map +1 -0
  85. package/dist/AgentTaskContext.js +26 -0
  86. package/dist/AgentTaskContext.js.map +1 -0
  87. package/dist/AgentTool.d.ts +87 -0
  88. package/dist/AgentTool.d.ts.map +1 -0
  89. package/dist/AgentTool.js +5 -0
  90. package/dist/AgentTool.js.map +1 -0
  91. package/dist/index.d.ts +24 -1
  92. package/dist/index.d.ts.map +1 -1
  93. package/dist/index.js +31 -1
  94. package/dist/index.js.map +1 -1
  95. package/dist/models.d.ts +62 -0
  96. package/dist/models.d.ts.map +1 -0
  97. package/dist/models.js +185 -0
  98. package/dist/models.js.map +1 -0
  99. package/package.json +44 -37
@@ -0,0 +1,95 @@
1
+ import type { SessionAssistantBlock, SessionMessage, SessionSystemMessage, SessionToolResultMessage, SessionUserMessage } from "@slopus/happy-providers";
2
+ import type { Context } from "@steve.kite/stdlib";
3
+ /**
4
+ * One record of the main context store. Only content that is part of the model context lives
5
+ * here: user messages enter when a turn consumes them, assistant output is appended one finished
6
+ * block at a time, and tool results follow the blocks that called them, so records always arrive
7
+ * in context order and consecutive block records reassemble into one assistant message. A
8
+ * compaction record carries the complete replacement context — the messages that stay — and is
9
+ * written in the same transaction that physically deletes the superseded records, so it opens
10
+ * the store; the records after it append as usual.
11
+ */
12
+ export type AgentRecord = {
13
+ readonly type: "user";
14
+ readonly message: SessionUserMessage;
15
+ } | {
16
+ readonly type: "block";
17
+ readonly block: SessionAssistantBlock;
18
+ } | {
19
+ readonly type: "tool";
20
+ readonly message: SessionToolResultMessage;
21
+ } | {
22
+ readonly type: "system";
23
+ readonly message: SessionSystemMessage;
24
+ } | {
25
+ readonly type: "compaction";
26
+ readonly messages: readonly SessionMessage[];
27
+ /**
28
+ * Whether inference should continue from the replacement's tail. A summary is not a
29
+ * request however it happens to end, but a replacement also preserves messages that
30
+ * joined after its snapshot. The rewrite is the only place that knows whether its tail
31
+ * came from the summary or that live suffix.
32
+ */
33
+ readonly continuesInference?: boolean;
34
+ };
35
+ /**
36
+ * Storage for one agent: an append-only main context store plus a sorted key-value store held
37
+ * alongside it. A sent message is first written under a `pending.` key ordered by append time;
38
+ * it reaches the main store only when a turn consumes it into the context, and its pending key
39
+ * is deleted at that moment. Exactly one owner connects to a store, and the agent serializes its
40
+ * own record and bookkeeping writes through one lock, so history order always matches storage
41
+ * order. Key-value operations — a feature's or a tool's — run as they come, so each one has to be
42
+ * atomic on its own, but no implementation ever has to defend against a second owner.
43
+ */
44
+ export interface AgentPersistence {
45
+ /**
46
+ * Run work atomically. The implementation opens a transaction and passes work a derived
47
+ * context that its own operations recognize; how the transaction rides on that context is
48
+ * entirely the implementation's business. Work resolving commits every operation; a thrown
49
+ * error rolls them all back.
50
+ */
51
+ transaction<Result>(ctx: Context, work: (ctx: Context) => Promise<Result>): Promise<Result>;
52
+ /** Every record in the main context store, in append order. */
53
+ load(ctx: Context): Promise<readonly AgentRecord[]>;
54
+ /** Add one more record to the end of the main context store. */
55
+ append(ctx: Context, record: AgentRecord): Promise<void>;
56
+ /**
57
+ * Physically delete every record in the main context store. Called only inside the
58
+ * compaction transaction, immediately before the replacement compaction record is appended,
59
+ * so the deletion and the replacement commit atomically.
60
+ */
61
+ clearRecords(ctx: Context): Promise<void>;
62
+ /** Every stored entry whose key starts with the prefix, sorted by key. */
63
+ readValues(ctx: Context, prefix: string): Promise<readonly {
64
+ readonly key: string;
65
+ readonly value: unknown;
66
+ }[]>;
67
+ /** Store the value under `key`, replacing whatever was there before. */
68
+ writeValue(ctx: Context, key: string, value: unknown): Promise<void>;
69
+ /**
70
+ * Write the value only if the key is absent, and report whether this call is the one that
71
+ * wrote it. The check and the write are a single atomic step, so of two writers racing for
72
+ * the same key exactly one is told it won — which is what makes a durable identity, such as
73
+ * an agent's creation record, safe to claim from more than one owner at a time.
74
+ */
75
+ writeValueIfAbsent(ctx: Context, key: string, value: unknown): Promise<boolean>;
76
+ /**
77
+ * Write the value only if the stored one is still what the caller decided from, and report
78
+ * whether this call is the one that wrote it. The comparison and the write are a single
79
+ * atomic step, so a read-decide-write sequence can be made safe against another owner who
80
+ * decided from the same value: the loser is told it lost and decides again, instead of
81
+ * overwriting a decision it never saw. Absence is a value like any other, and matches an
82
+ * expectation of `undefined`.
83
+ */
84
+ writeValueIfUnchanged(ctx: Context, key: string, expected: unknown, value: unknown): Promise<boolean>;
85
+ /** Remove the entry stored under `key`, if any. */
86
+ deleteValue(ctx: Context, key: string): Promise<void>;
87
+ /**
88
+ * Delete the key and report whether this call is the one that removed it. The check and the
89
+ * deletion are a single atomic step and take effect at once — a transaction that later rolls
90
+ * back restores the entry. This is how a durable queue entry is claimed: of several owners
91
+ * over one store racing to consume the same message, exactly one is told it won.
92
+ */
93
+ deleteValueIfPresent(ctx: Context, key: string): Promise<boolean>;
94
+ }
95
+ //# sourceMappingURL=AgentPersistence.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentPersistence.d.ts","sourceRoot":"","sources":["../sources/AgentPersistence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,qBAAqB,EACrB,cAAc,EACd,oBAAoB,EACpB,wBAAwB,EACxB,kBAAkB,EACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAA;CAAE,GACrE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GACnE;IACI,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACzC,CAAC;AAER;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5F,+DAA+D;IAC/D,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IACpD,gEAAgE;IAChE,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,0EAA0E;IAC1E,UAAU,CACN,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,GACf,OAAO,CAAC,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC,CAAC;IACzE,wEAAwE;IACxE,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE;;;;;OAKG;IACH,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChF;;;;;;;OAOG;IACH,qBAAqB,CACjB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,OAAO,GACf,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,mDAAmD;IACnD,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD;;;;;OAKG;IACH,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrE"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=AgentPersistence.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentPersistence.js","sourceRoot":"","sources":["../sources/AgentPersistence.ts"],"names":[],"mappings":""}
@@ -0,0 +1,22 @@
1
+ import type { BaseProvider, ProviderModelCompatibilityType } from "@slopus/happy-providers";
2
+ /**
3
+ * Mutable registry of happy-providers instances keyed by a caller-supplied provider ID, so the
4
+ * same provider class can be registered under several IDs (for example per credential). Each
5
+ * entry carries its compatibility type, which decides how far a model change can go before the
6
+ * conversation must reset. Providers can be added and removed while the process runs; lookups
7
+ * return the live reference or null when absent.
8
+ */
9
+ export declare class AgentProviders {
10
+ #private;
11
+ /** Register a provider under `id`. Throws if that ID is already registered. */
12
+ add(id: string, provider: BaseProvider, type: ProviderModelCompatibilityType): void;
13
+ /** Unregister the provider at `id`. Returns whether one was actually removed. */
14
+ remove(id: string): boolean;
15
+ /** The live provider instance registered at `id`, or null when none is registered. */
16
+ get(id: string): BaseProvider | null;
17
+ /** The compatibility type the provider at `id` was registered with, or null when absent. */
18
+ typeOf(id: string): ProviderModelCompatibilityType | null;
19
+ /** Every currently registered provider ID. */
20
+ get ids(): readonly string[];
21
+ }
22
+ //# sourceMappingURL=AgentProviders.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentProviders.d.ts","sourceRoot":"","sources":["../sources/AgentProviders.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,8BAA8B,EAAE,MAAM,yBAAyB,CAAC;AAE5F;;;;;;GAMG;AACH,qBAAa,cAAc;;IAOvB,+EAA+E;IAC/E,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,8BAA8B,GAAG,IAAI,CAKlF;IAED,iFAAiF;IACjF,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE1B;IAED,sFAAsF;IACtF,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAEnC;IAED,4FAA4F;IAC5F,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,8BAA8B,GAAG,IAAI,CAExD;IAED,8CAA8C;IAC9C,IAAI,GAAG,IAAI,SAAS,MAAM,EAAE,CAE3B;CACJ"}
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Mutable registry of happy-providers instances keyed by a caller-supplied provider ID, so the
3
+ * same provider class can be registered under several IDs (for example per credential). Each
4
+ * entry carries its compatibility type, which decides how far a model change can go before the
5
+ * conversation must reset. Providers can be added and removed while the process runs; lookups
6
+ * return the live reference or null when absent.
7
+ */
8
+ export class AgentProviders {
9
+ /** Registered providers keyed by their caller-supplied ID, alongside their compatibility type. */
10
+ #providers = new Map();
11
+ /** Register a provider under `id`. Throws if that ID is already registered. */
12
+ add(id, provider, type) {
13
+ if (this.#providers.has(id)) {
14
+ throw new Error(`Provider "${id}" is already registered.`);
15
+ }
16
+ this.#providers.set(id, { provider, type });
17
+ }
18
+ /** Unregister the provider at `id`. Returns whether one was actually removed. */
19
+ remove(id) {
20
+ return this.#providers.delete(id);
21
+ }
22
+ /** The live provider instance registered at `id`, or null when none is registered. */
23
+ get(id) {
24
+ return this.#providers.get(id)?.provider ?? null;
25
+ }
26
+ /** The compatibility type the provider at `id` was registered with, or null when absent. */
27
+ typeOf(id) {
28
+ return this.#providers.get(id)?.type ?? null;
29
+ }
30
+ /** Every currently registered provider ID. */
31
+ get ids() {
32
+ return [...this.#providers.keys()];
33
+ }
34
+ }
35
+ //# sourceMappingURL=AgentProviders.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentProviders.js","sourceRoot":"","sources":["../sources/AgentProviders.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IACvB,kGAAkG;IACzF,UAAU,GAAG,IAAI,GAAG,EAG1B,CAAC;IAEJ,+EAA+E;IAC/E,GAAG,CAAC,EAAU,EAAE,QAAsB,EAAE,IAAoC;QACxE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,aAAa,EAAE,0BAA0B,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,iFAAiF;IACjF,MAAM,CAAC,EAAU;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,sFAAsF;IACtF,GAAG,CAAC,EAAU;QACV,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,QAAQ,IAAI,IAAI,CAAC;IACrD,CAAC;IAED,4FAA4F;IAC5F,MAAM,CAAC,EAAU;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;IACjD,CAAC;IAED,8CAA8C;IAC9C,IAAI,GAAG;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;CACJ"}
@@ -0,0 +1,41 @@
1
+ import type { SessionUserMessage } from "@slopus/happy-providers";
2
+ import type { Context } from "@steve.kite/stdlib";
3
+ import type { Agent } from "./Agent.js";
4
+ import type { AgentBaseMessageOptions } from "./AgentBase.js";
5
+ /**
6
+ * Whether this caller may be told that `agentId` durably accepted a message. Acceptance is a
7
+ * queue write under that agent's own persistence lock, so waiting for it is safe from anywhere
8
+ * except inside that agent's loop, which is holding the lock the write needs. The proof is the
9
+ * caller's context naming a different agent; a context naming none proves nothing.
10
+ */
11
+ export declare function acceptanceIsWaitable(ctx: Context, target: string): boolean;
12
+ /**
13
+ * A reference to an agent for code that runs inside one — a feature hook, or a tool the run loop
14
+ * is waiting on. No operation here waits for a run loop: `compact` and `abort` are requests that
15
+ * resolve once they have been made, and there is no `close`, `waitForIdle` or `start`, each of
16
+ * which is whole-agent lifetime owned by whoever created the agent and nothing *but* the wait
17
+ * this caller must not make.
18
+ *
19
+ * Messages are different, because accepting one is a durable queue write rather than a turn.
20
+ * Addressed to another agent, `steer` and `send` resolve once the message really is part of that
21
+ * agent's conversation and reject when the write fails, so a caller routing work elsewhere knows
22
+ * whether it arrived. Addressed to the agent the caller is running inside — whose loop would have
23
+ * to perform that write — the message is queued and not waited for. The context decides, since it
24
+ * names the agent the caller is in; a context that names none proves nothing and waits for
25
+ * nothing.
26
+ */
27
+ export declare class AgentRef {
28
+ #private;
29
+ constructor(agent: Agent);
30
+ /** The wrapped agent's ID. */
31
+ get id(): string;
32
+ /** Queue a message that injects as soon as the current response and its tool batch finish. */
33
+ steer(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<void>;
34
+ /** Queue a message that injects when the agent would otherwise stop. */
35
+ send(ctx: Context, message: SessionUserMessage, options?: AgentBaseMessageOptions): Promise<void>;
36
+ /** Ask the agent to compact, which it does between turns. */
37
+ compact(ctx: Context): Promise<void>;
38
+ /** Cancel the agent's active turn. */
39
+ abort(ctx: Context): Promise<void>;
40
+ }
41
+ //# sourceMappingURL=AgentRef.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentRef.d.ts","sourceRoot":"","sources":["../sources/AgentRef.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAG9D;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAG1E;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,QAAQ;;IAIjB,YAAY,KAAK,EAAE,KAAK,EAEvB;IAED,8BAA8B;IAC9B,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,8FAA8F;IACxF,KAAK,CACP,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC,CAKf;IAED,wEAAwE;IAClE,IAAI,CACN,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC,CAKf;IAED,6DAA6D;IACvD,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzC;IAED,sCAAsC;IAChC,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvC;CACJ"}
@@ -0,0 +1,60 @@
1
+ import { agentId } from "./AgentContexts.js";
2
+ /**
3
+ * Whether this caller may be told that `agentId` durably accepted a message. Acceptance is a
4
+ * queue write under that agent's own persistence lock, so waiting for it is safe from anywhere
5
+ * except inside that agent's loop, which is holding the lock the write needs. The proof is the
6
+ * caller's context naming a different agent; a context naming none proves nothing.
7
+ */
8
+ export function acceptanceIsWaitable(ctx, target) {
9
+ const caller = agentId(ctx);
10
+ return caller !== undefined && caller !== target;
11
+ }
12
+ /**
13
+ * A reference to an agent for code that runs inside one — a feature hook, or a tool the run loop
14
+ * is waiting on. No operation here waits for a run loop: `compact` and `abort` are requests that
15
+ * resolve once they have been made, and there is no `close`, `waitForIdle` or `start`, each of
16
+ * which is whole-agent lifetime owned by whoever created the agent and nothing *but* the wait
17
+ * this caller must not make.
18
+ *
19
+ * Messages are different, because accepting one is a durable queue write rather than a turn.
20
+ * Addressed to another agent, `steer` and `send` resolve once the message really is part of that
21
+ * agent's conversation and reject when the write fails, so a caller routing work elsewhere knows
22
+ * whether it arrived. Addressed to the agent the caller is running inside — whose loop would have
23
+ * to perform that write — the message is queued and not waited for. The context decides, since it
24
+ * names the agent the caller is in; a context that names none proves nothing and waits for
25
+ * nothing.
26
+ */
27
+ export class AgentRef {
28
+ /** The agent this reference wraps. */
29
+ #agent;
30
+ constructor(agent) {
31
+ this.#agent = agent;
32
+ }
33
+ /** The wrapped agent's ID. */
34
+ get id() {
35
+ return this.#agent.id;
36
+ }
37
+ /** Queue a message that injects as soon as the current response and its tool batch finish. */
38
+ async steer(ctx, message, options) {
39
+ await this.#agent.steer(ctx, message, {
40
+ ...options,
41
+ await: acceptanceIsWaitable(ctx, this.#agent.id),
42
+ });
43
+ }
44
+ /** Queue a message that injects when the agent would otherwise stop. */
45
+ async send(ctx, message, options) {
46
+ await this.#agent.send(ctx, message, {
47
+ ...options,
48
+ await: acceptanceIsWaitable(ctx, this.#agent.id),
49
+ });
50
+ }
51
+ /** Ask the agent to compact, which it does between turns. */
52
+ async compact(ctx) {
53
+ await this.#agent.compact(ctx, { await: false });
54
+ }
55
+ /** Cancel the agent's active turn. */
56
+ async abort(ctx) {
57
+ await this.#agent.abort(ctx, { await: false });
58
+ }
59
+ }
60
+ //# sourceMappingURL=AgentRef.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentRef.js","sourceRoot":"","sources":["../sources/AgentRef.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAY,EAAE,MAAc;IAC7D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,MAAM,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,QAAQ;IACjB,sCAAsC;IAC7B,MAAM,CAAQ;IAEvB,YAAY,KAAY;QACpB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACxB,CAAC;IAED,8BAA8B;IAC9B,IAAI,EAAE;QACF,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;IAC1B,CAAC;IAED,8FAA8F;IAC9F,KAAK,CAAC,KAAK,CACP,GAAY,EACZ,OAA2B,EAC3B,OAAiC;QAEjC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE;YAClC,GAAG,OAAO;YACV,KAAK,EAAE,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;SACnD,CAAC,CAAC;IACP,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,IAAI,CACN,GAAY,EACZ,OAA2B,EAC3B,OAAiC;QAEjC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE;YACjC,GAAG,OAAO;YACV,KAAK,EAAE,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;SACnD,CAAC,CAAC;IACP,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,OAAO,CAAC,GAAY;QACtB,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,sCAAsC;IACtC,KAAK,CAAC,KAAK,CAAC,GAAY;QACpB,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACnD,CAAC;CACJ"}
@@ -0,0 +1,19 @@
1
+ import type { AgentKV } from "./AgentKV.js";
2
+ import type { AgentPersistence } from "./AgentPersistence.js";
3
+ /** What an `AgentStorage` is built from. */
4
+ export interface AgentStorageOptions {
5
+ /** Shared key-value storage used for state spanning all agents. */
6
+ readonly kv: AgentKV;
7
+ /** Produce the isolated persistence used by one agent. */
8
+ readonly persistence: (agentId: string) => AgentPersistence;
9
+ }
10
+ /** Storage roots shared by an `AgentSystemLocal` collection. */
11
+ export declare class AgentStorage {
12
+ #private;
13
+ /** Shared key-value storage used for state spanning all agents. */
14
+ readonly kv: AgentKV;
15
+ constructor(options: AgentStorageOptions);
16
+ /** The isolated persistence for the given agent. */
17
+ persistence(agentId: string): AgentPersistence;
18
+ }
19
+ //# sourceMappingURL=AgentStorage.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentStorage.d.ts","sourceRoot":"","sources":["../sources/AgentStorage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAChC,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,gBAAgB,CAAC;CAC/D;AAED,gEAAgE;AAChE,qBAAa,YAAY;;IACrB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IAIrB,YAAY,OAAO,EAAE,mBAAmB,EAGvC;IAED,oDAAoD;IACpD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAE7C;CACJ"}
@@ -0,0 +1,16 @@
1
+ /** Storage roots shared by an `AgentSystemLocal` collection. */
2
+ export class AgentStorage {
3
+ /** Shared key-value storage used for state spanning all agents. */
4
+ kv;
5
+ /** Produces the isolated persistence used by one agent. */
6
+ #persistence;
7
+ constructor(options) {
8
+ this.kv = options.kv;
9
+ this.#persistence = options.persistence;
10
+ }
11
+ /** The isolated persistence for the given agent. */
12
+ persistence(agentId) {
13
+ return this.#persistence(agentId);
14
+ }
15
+ }
16
+ //# sourceMappingURL=AgentStorage.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentStorage.js","sourceRoot":"","sources":["../sources/AgentStorage.ts"],"names":[],"mappings":"AAWA,gEAAgE;AAChE,MAAM,OAAO,YAAY;IACrB,mEAAmE;IAC1D,EAAE,CAAU;IACrB,2DAA2D;IAClD,YAAY,CAAwC;IAE7D,YAAY,OAA4B;QACpC,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC;QACrB,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAC5C,CAAC;IAED,oDAAoD;IACpD,WAAW,CAAC,OAAe;QACvB,OAAO,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;CACJ"}
@@ -0,0 +1,50 @@
1
+ import type { SessionMessage, SessionUserMessage } from "@slopus/happy-providers";
2
+ import type { Context } from "@steve.kite/stdlib";
3
+ import type { Agent } from "./Agent.js";
4
+ import type { AgentBaseAwaitOptions, AgentBaseMessageOptions } from "./AgentBase.js";
5
+ import type { AgentConfig } from "./AgentConfig.js";
6
+ import type { AgentModel } from "./AgentModel.js";
7
+ /** Conversation state installed atomically before a newly created agent starts. */
8
+ export interface AgentInitialContext {
9
+ /** The conversation installed as the agent's history before its first turn runs. */
10
+ readonly messages: readonly SessionMessage[];
11
+ }
12
+ /**
13
+ * A collection of agents addressed by ID: what an owner can ask of the agents it runs. An agent
14
+ * exists only once it has been created with its configuration, which is persisted and stays in
15
+ * effect for the agent's whole life; resolving one that was never created is an error.
16
+ *
17
+ * This is the full surface, including the operations that wait for an agent's run loop to reach a
18
+ * particular point — `delete`, and anything reached through the returned `Agent`. Those are for
19
+ * the caller that owns the agents' lifetime. Code running *inside* an agent, such as a feature
20
+ * hook or a tool, is waited for by that loop and must not wait for it in turn: it should hold an
21
+ * `AgentSystemRef`, whose every operation returns without waiting for a loop.
22
+ */
23
+ export interface AgentSystem {
24
+ /** The models this collection offers its agents. */
25
+ readonly models: readonly AgentModel[];
26
+ /**
27
+ * Create an agent with a new system-generated cuid2 identity and the configuration it keeps
28
+ * for its whole life. The configuration and optional initial context are persisted before
29
+ * the agent runs; a creation that fails to produce an agent leaves no identity behind.
30
+ */
31
+ create(ctx: Context, config: AgentConfig, initialContext?: AgentInitialContext): Promise<Agent>;
32
+ /** Close an agent and release its identity, so the same ID can be created again. */
33
+ delete(ctx: Context, agentId: string): Promise<void>;
34
+ /** The configuration an agent was created with, or undefined when there is no such agent. */
35
+ config(ctx: Context, agentId: string): Promise<AgentConfig | undefined>;
36
+ /** The live agent for an ID, loading it if this process has not seen it yet. */
37
+ resolve(ctx: Context, agentId: string): Promise<Agent>;
38
+ /**
39
+ * Queue a user message for an agent, injected as soon as its current response and tool batch
40
+ * finish.
41
+ */
42
+ steer(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<void>;
43
+ /** Queue a user message for an agent that injects only when the agent would otherwise stop. */
44
+ send(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<void>;
45
+ /** Cancel an agent's active turn, leaving its queued messages durable for the next one. */
46
+ abort(ctx: Context, agentId: string, options?: AgentBaseAwaitOptions): Promise<void>;
47
+ /** Ask an agent for its conversation to be replaced by the provider's summary of it. */
48
+ compact(ctx: Context, agentId: string, options?: AgentBaseAwaitOptions): Promise<void>;
49
+ }
50
+ //# sourceMappingURL=AgentSystem.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentSystem.d.ts","sourceRoot":"","sources":["../sources/AgentSystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IAChC,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CAChD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IACxB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IAEvC;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAEhG,oFAAoF;IACpF,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD,6FAA6F;IAC7F,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAExE,gFAAgF;IAChF,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAEvD;;;OAGG;IACH,KAAK,CACD,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAAG,qBAAqB,GAC1D,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,+FAA+F;IAC/F,IAAI,CACA,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAAG,qBAAqB,GAC1D,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,2FAA2F;IAC3F,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErF,wFAAwF;IACxF,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1F"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=AgentSystem.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentSystem.js","sourceRoot":"","sources":["../sources/AgentSystem.ts"],"names":[],"mappings":""}
@@ -0,0 +1,15 @@
1
+ import { type Context } from "@steve.kite/stdlib";
2
+ import type { AgentSystemRef } from "./AgentSystemRef.js";
3
+ /**
4
+ * Carry the collection that owns an agent and its features, as a reference.
5
+ *
6
+ * Only the reference travels on a context. Everything that reads one — a feature hook, a tool —
7
+ * is code some run loop is waiting for, while the owner's surface holds the operations that wait
8
+ * for a loop to reach a particular point. A collection therefore puts an `AgentSystemRef` on
9
+ * every context it derives, and agents come back from it as `AgentRef`, so nothing reached
10
+ * through a context can wait for the loop that is waiting for it.
11
+ */
12
+ export declare function withAgentSystem(ctx: Context, value: AgentSystemRef): Context;
13
+ /** The collection owning the current feature or agent operation. */
14
+ export declare function agentSystem(ctx: Context): AgentSystemRef | undefined;
15
+ //# sourceMappingURL=AgentSystemContext.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentSystemContext.d.ts","sourceRoot":"","sources":["../sources/AgentSystemContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ1D;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAE5E;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAEpE"}
@@ -0,0 +1,20 @@
1
+ import { createContextNamespace } from "@steve.kite/stdlib";
2
+ /** The context slot that carries the collection owning the current agent or feature operation. */
3
+ const agentSystemNamespace = createContextNamespace("happyAgent.agentSystem", undefined);
4
+ /**
5
+ * Carry the collection that owns an agent and its features, as a reference.
6
+ *
7
+ * Only the reference travels on a context. Everything that reads one — a feature hook, a tool —
8
+ * is code some run loop is waiting for, while the owner's surface holds the operations that wait
9
+ * for a loop to reach a particular point. A collection therefore puts an `AgentSystemRef` on
10
+ * every context it derives, and agents come back from it as `AgentRef`, so nothing reached
11
+ * through a context can wait for the loop that is waiting for it.
12
+ */
13
+ export function withAgentSystem(ctx, value) {
14
+ return agentSystemNamespace.set(ctx, value);
15
+ }
16
+ /** The collection owning the current feature or agent operation. */
17
+ export function agentSystem(ctx) {
18
+ return agentSystemNamespace.get(ctx);
19
+ }
20
+ //# sourceMappingURL=AgentSystemContext.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentSystemContext.js","sourceRoot":"","sources":["../sources/AgentSystemContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAgB,MAAM,oBAAoB,CAAC;AAI1E,kGAAkG;AAClG,MAAM,oBAAoB,GAAG,sBAAsB,CAC/C,wBAAwB,EACxB,SAAS,CACZ,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY,EAAE,KAAqB;IAC/D,OAAO,oBAAoB,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AAChD,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,WAAW,CAAC,GAAY;IACpC,OAAO,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC"}
@@ -0,0 +1,103 @@
1
+ import type { SessionUserMessage } from "@slopus/happy-providers";
2
+ import { type Context } from "@steve.kite/stdlib";
3
+ import { Agent } from "./Agent.js";
4
+ import { type AgentBaseAwaitOptions, type AgentBaseMessageOptions } from "./AgentBase.js";
5
+ import { type AgentConfig } from "./AgentConfig.js";
6
+ import type { AgentFeature } from "./AgentFeature.js";
7
+ import type { AgentModel } from "./AgentModel.js";
8
+ import type { AgentProviders } from "./AgentProviders.js";
9
+ import type { AgentStorage } from "./AgentStorage.js";
10
+ import type { AgentInitialContext, AgentSystem } from "./AgentSystem.js";
11
+ /** Everything `AgentSystemLocal` needs to build and run the agents in its collection. */
12
+ export interface AgentSystemLocalOptions {
13
+ /**
14
+ * The features every agent in this collection runs with, given as instances the caller has
15
+ * already built and ready to serve. One instance serves the whole collection: a hook is told
16
+ * which agent it is running for by the scope it is handed, so any per-agent state a feature
17
+ * keeps in memory has to be keyed by that ID rather than held as a single value.
18
+ */
19
+ readonly features?: readonly AgentFeature[];
20
+ /** The registry providers are resolved from when an agent is built. */
21
+ readonly providers: AgentProviders;
22
+ /** The registry ID of the provider new agents are created with. */
23
+ readonly provider: string;
24
+ /** The models this collection offers its agents. */
25
+ readonly models: readonly AgentModel[];
26
+ }
27
+ /**
28
+ * The `AgentSystem` backed by this process: it lazily builds and owns the `Agent` instances for
29
+ * the identities its storage holds. Concurrent resolutions of the same ID share one load, while a
30
+ * failed load is forgotten so a later resolution can retry.
31
+ *
32
+ * Identity is durable and shared, so more than one live collection can be working over one
33
+ * storage. Everything below therefore serializes per agent rather than per collection — a
34
+ * collection-wide lock would make one agent's feature load block every other agent, including one
35
+ * that load itself resolves — and treats storage, not memory, as the authority on who exists.
36
+ *
37
+ * This is the owner's handle, and some of what it offers waits for an agent to reach a point only
38
+ * that agent's run loop can bring it to. Hand an `AgentSystemRef` to anything running inside an
39
+ * agent instead.
40
+ */
41
+ export declare class AgentSystemLocal implements AgentSystem {
42
+ #private;
43
+ /** The models this collection offers its agents. */
44
+ readonly models: readonly AgentModel[];
45
+ /**
46
+ * Bring up a collection over one storage and carry on where the last process left off.
47
+ *
48
+ * A collection is not a passive registry that happens to be asked for agents later: whatever
49
+ * was running when the previous process ended is still owed an answer, and this is what
50
+ * makes it happen. Every identity the storage holds is examined, and each one that owes work
51
+ * is resolved and resumed, so by the time this returns the collection is not merely built
52
+ * but running. An identity another owner is still creating is left alone, since until that
53
+ * creation commits there is no agent to resume.
54
+ */
55
+ static create(ctx: Context, storage: AgentStorage, config: AgentSystemLocalOptions): Promise<AgentSystemLocal>;
56
+ /**
57
+ * Wire this collection to its storage, providers, and feature configuration, without reading
58
+ * any of it. Private: a collection is brought up by `create`, which also resumes the work
59
+ * the storage was left holding — building one without that is building half of it.
60
+ */
61
+ private constructor();
62
+ /**
63
+ * Create an agent with the configuration it keeps for its whole life, and resolve it. The
64
+ * identity is allocated here and nowhere else: it is a cuid2, globally unique, so a new
65
+ * agent never lands on an identity that already exists or on a store something else wrote.
66
+ * The configuration is persisted before the agent runs, so every later process resolves the
67
+ * agent exactly as it was created.
68
+ *
69
+ * Nothing here is ever undone: an agent whose features refuse to load leaves an identity
70
+ * that exists, is resolvable, and will be built the next time something wants it. The
71
+ * alternative — writing a provisional identity and taking it back when the build fails —
72
+ * has to get the taking-back right in the presence of crashes and other owners, and a
73
+ * compensation that can itself fail is not a guarantee.
74
+ */
75
+ create(ctx: Context, config: AgentConfig, initialContext?: AgentInitialContext): Promise<Agent>;
76
+ /**
77
+ * Close an agent and release its identity, so the same ID can be created again. Used to undo
78
+ * a creation whose follow-up work failed; an ID that was never created is left alone.
79
+ *
80
+ * What the agent wrote is left where it is. The close finishes first, so the store holds a
81
+ * whole conversation rather than a truncated one, and that record is worth more here than the
82
+ * space it takes: whoever deleted the agent may still want to know what it did. The next
83
+ * identity created under this ID starts from an empty store all the same, because creation is
84
+ * what clears it.
85
+ */
86
+ delete(ctx: Context, agentId: string): Promise<void>;
87
+ /** The configuration an agent was created with, or undefined when there is no such agent. */
88
+ config(ctx: Context, agentId: string): Promise<AgentConfig | undefined>;
89
+ /**
90
+ * The live agent for an ID, loading and starting it if this process has not seen it yet.
91
+ * Concurrent resolutions of the same ID share one load.
92
+ */
93
+ resolve(ctx: Context, agentId: string): Promise<Agent>;
94
+ /** Queue a steered message for an agent. */
95
+ steer(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<void>;
96
+ /** Queue a message for an agent. */
97
+ send(ctx: Context, agentId: string, message: SessionUserMessage, options?: AgentBaseMessageOptions & AgentBaseAwaitOptions): Promise<void>;
98
+ /** Cancel an agent's active turn, leaving its queued messages durable for the next one. */
99
+ abort(ctx: Context, agentId: string, options?: AgentBaseAwaitOptions): Promise<void>;
100
+ /** Ask an agent for its conversation to be replaced by the provider's summary of it. */
101
+ compact(ctx: Context, agentId: string, options?: AgentBaseAwaitOptions): Promise<void>;
102
+ }
103
+ //# sourceMappingURL=AgentSystemLocal.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AgentSystemLocal.d.ts","sourceRoot":"","sources":["../sources/AgentSystemLocal.ts"],"names":[],"mappings":"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"}