@theokit/di-agent 0.3.0 → 0.5.0

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 (3) hide show
  1. package/CHANGELOG.md +92 -1
  2. package/README.md +27 -0
  3. package/package.json +8 -6
package/CHANGELOG.md CHANGED
@@ -1,5 +1,89 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.5.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 1e880aa: The `@theokit/sdk` peer range admits the published `latest`. `>=4.0.1 <5` excluded `5.9.0`, so the
8
+ dependency gate counted this package among those a release would strand
9
+ (usetheokit/shared-workflows#64).
10
+
11
+ **Both ends were installed and run, not reasoned about from a changelog:**
12
+
13
+ | sdk | typecheck | suite |
14
+ | ---------------------------------------------------- | --------- | --------------------- |
15
+ | 4.0.1 — the declared floor, previously untested here | clean | 118 passed, 2 skipped |
16
+ | 5.9.0 — the published latest | clean | 118 passed, 2 skipped |
17
+
18
+ No code changed: the two imports this package makes — `@theokit/sdk` and `@theokit/sdk/workflow` —
19
+ resolve identically across the major.
20
+
21
+ A clean consumer install of this package's tarball with `@theokit/sdk@5.9.0` reports no `ERESOLVE`
22
+ and resolves **one** copy of the sdk. That check is here because widening a peer range is how
23
+ `@theokit/studio` ended up with two copies in a consumer's tree, and a range that installs is not the
24
+ same claim as a range that installs once.
25
+
26
+ ### Patch Changes
27
+
28
+ - e3f55b2: The README states what the decorators do and what reads them, because the export list reads like a
29
+ promise that something runs them (usetheokit/theokit-di#70).
30
+
31
+ `@Tool`, `@SubAgent`, `@Squad`, `@Workflow`, `@Step`, `@Cron`, `@Hitl`, `@Retriever`, `@Reranker`
32
+ and their siblings write metadata onto a class and nothing else. The split is deliberate — a
33
+ declaration and the runtime that acts on it version independently — but a consumer reading the
34
+ exports has no way to learn that, and reasonably concludes `@Workflow` executes something.
35
+
36
+ Measured across every repository in this ecosystem, excluding `node_modules`: **no consumer outside
37
+ this package reads any of the readers, `@theokit/sdk` included.** Inside it, `workflow-builder.ts`
38
+ reads `readStepMetadata` and `readWorkflowMetadata`; the other fourteen readers have no consumer
39
+ anywhere. The issue reported zero readers in total — the two in `workflow-builder.ts` are the
40
+ refinement, and they matter because the docblock in `decorators/tool.ts` says _"nothing in this
41
+ package acts on it"_, which is true of `@Tool` and not of `@Workflow`.
42
+
43
+ Nothing is retired and no behaviour changes. A declaration surface waiting for a consumer is a fine
44
+ thing to be, stated; the README now says which one it is, and points at `AgentBuilder` for someone
45
+ choosing an authoring surface that executes today.
46
+
47
+ `tests/decorator-consumers.test.ts` keeps the table honest in both directions: wiring a reader fails
48
+ until the table names it, and naming a decorator the code does not read fails too. Both were proven
49
+ by breaking them — the first assertion was written against the whole README, passed with a reader
50
+ wired, and was rewritten to read the table row.
51
+
52
+ ## 0.4.0
53
+
54
+ ### Minor Changes
55
+
56
+ - 33670b7: Realign the `@theokit/sdk` peer with the SDK this package actually imports.
57
+
58
+ **Install-contract break.** `@theokit/sdk` moves from `^1.3.0` to `>=4.0.1 <5`. An app pinned below
59
+ 4 stops satisfying the peer. Minor bump because the version is still 0.x, where minor is the
60
+ breaking slot.
61
+
62
+ The old range described nothing that existed. `src/workflow-builder.ts` imports
63
+ `@theokit/sdk/workflow` at runtime, the package is developed and tested against the modern SDK, and
64
+ the published SDK has been on 4.x for months — so `npm i @theokit/di-agent @theokit/sdk@^4` ended in
65
+ `ERESOLVE`, and pnpm users got a peer warning for a combination that was never supported.
66
+ (usetheokit/theokit-di#40)
67
+
68
+ Verified at both ends of the new range: the suite passes against 4.0.1 and against 4.57.0. The
69
+ `@theokit/sdk` devDependency moves to `^4.57.0` for the same reason the range went stale unnoticed —
70
+ CI was resolving 1.x, compiling against it, and going green on a combination no consumer installs.
71
+
72
+ ### Patch Changes
73
+
74
+ - 5bb0600: O peer range do `@theokit/di` deixa de prometer uma versão em que o pacote não funciona.
75
+
76
+ Declarava `^0.1.0-next.0 || ^0.2.0`, e o piso resolvível disso é `0.1.0` — que **não exporta
77
+ `METADATA_KEYS`**, um símbolo que `src/` importa. Um consumidor que resolvesse para 0.1.0 instalava
78
+ sem erro e partia nos decorators.
79
+
80
+ Medido antes de escrever o novo range, versão a versão: `0.1.0` não tem o símbolo, `0.1.1` tem,
81
+ `0.2.0` tem. O range passa a ser `>=0.1.1 <0.3`, que é o que a suíte prova.
82
+
83
+ Encontrado pelo leg `suite at the bottom of every declared range` do dep-check, que instala o piso
84
+ de cada range declarado e corre os testes contra ele — 31 falharam. É a única forma de um piso
85
+ mentiroso aparecer: nada mais no CI instala a versão mínima.
86
+
3
87
  All notable changes to `@theokit/di-agent` are documented in this file.
4
88
 
5
89
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
@@ -7,6 +91,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
91
 
8
92
  ## [Unreleased]
9
93
 
94
+ ### Fixed
95
+
96
+ - Installing this package next to the `@theokit/sdk` it actually needs no longer fails. The declared
97
+ peer range was `^1.3.0` while the package imports `@theokit/sdk/workflow` at runtime and the SDK
98
+ has been on 4.x for months, so `npm i @theokit/di-agent @theokit/sdk@^4` ended in `ERESOLVE` and
99
+ pnpm users got a peer warning for a combination that was never supported. The range is now
100
+ `>=4.0.1 <5`, verified at both ends: the suite passes against 4.0.1 and against 4.57.0. (#40)
101
+
10
102
  ## [0.3.0] - 2026-08-21
11
103
 
12
104
  ### Added
@@ -32,7 +124,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
32
124
  - JSDoc and comments no longer cite plan tasks or edge-case identifiers that exist in no repository a reader can reach.
33
125
  - **Breaking:** `readCronMetadata` and `readHitlMetadata` return a `ReadonlyMap` keyed by method name instead of a single object or `undefined`. `@Cron` and `@Hitl` kept one object per class, so decorating a second method silently discarded the first — a class with two scheduled routines quietly lost one. Both now accumulate per method, like the other fourteen decorators. Migration: `readCronMetadata(C)?.schedule` becomes `readCronMetadata(C).get("methodName")?.schedule`, and an undecorated class yields an empty map rather than `undefined` (#6).
34
126
 
35
-
36
127
  ## 0.2.0
37
128
 
38
129
  ### Minor Changes
package/README.md CHANGED
@@ -51,6 +51,33 @@ await container.runInRequest(async () => {
51
51
  });
52
52
  ```
53
53
 
54
+ ## The decorators record; they do not execute
55
+
56
+ `@Tool`, `@SubAgent`, `@Squad`, `@Workflow`, `@Step`, `@Cron`, `@Hitl`, `@Retriever`, `@Reranker`
57
+ and their siblings **write metadata onto a class and nothing else**. Each has a matching
58
+ `read*Metadata` reader, exported so a consumer can retrieve what was recorded.
59
+
60
+ That split is deliberate — it lets a declaration and the runtime that acts on it version
61
+ independently. What it means in practice is stated here rather than inferred from the export list,
62
+ because an export list that names `@Workflow` reads like a promise that something runs it.
63
+
64
+ **Measured 2026-09-17, across every repository in this ecosystem, excluding `node_modules`:**
65
+
66
+ | Decorator family | Read by |
67
+ | --- | --- |
68
+ | `@Workflow`, `@Step` | `workflow-builder.ts`, inside this package |
69
+ | the other fourteen | nothing, anywhere |
70
+
71
+ No consumer outside this package reads any of them, including `@theokit/sdk`.
72
+
73
+ **This is a declaration surface waiting for a consumer, and that is a fine thing to be — stated.**
74
+ If you are choosing an authoring surface today, `AgentBuilder` in `@theokit/agents` is the one that
75
+ executes. Reach for these when you want a class to *carry* a declaration that your own code reads
76
+ back through `read*Metadata`, which works exactly as documented.
77
+
78
+ `tests/decorator-consumers.test.ts` keeps this table honest: wiring a reader makes it fail until the
79
+ table says so.
80
+
54
81
  ## License
55
82
 
56
83
  Apache-2.0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theokit/di-agent",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "Agent-first DI integration for @theokit/di. Ships @InjectAgent() decorator + createAgentProvider() helper that produces a REQUEST-scoped Agent factory — so every HTTP request gets an isolated @theokit/sdk Agent automatically.",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://github.com/usetheokit/theokit-di#readme",
@@ -27,7 +27,8 @@
27
27
  "types": "./dist/index.d.cts",
28
28
  "default": "./dist/index.cjs"
29
29
  }
30
- }
30
+ },
31
+ "./package.json": "./package.json"
31
32
  },
32
33
  "files": [
33
34
  "dist",
@@ -43,13 +44,13 @@
43
44
  "Theo"
44
45
  ],
45
46
  "peerDependencies": {
46
- "@theokit/di": "^0.1.0-next.0 || ^0.2.0",
47
- "@theokit/sdk": "^1.3.0",
47
+ "@theokit/di": ">=0.1.1 <0.3",
48
+ "@theokit/sdk": ">=4.0.1 <6",
48
49
  "reflect-metadata": "^0.2.0"
49
50
  },
50
51
  "devDependencies": {
51
52
  "@swc/core": "^1.15.40",
52
- "@theokit/sdk": "^1.9.0",
53
+ "@theokit/sdk": "^5.9.0",
53
54
  "reflect-metadata": "^0.2.0",
54
55
  "tsup": "^8.5.0",
55
56
  "typedoc": "^0.28.19",
@@ -57,12 +58,13 @@
57
58
  "unplugin-swc": "^1.5.9",
58
59
  "vitest": "^4.1.8",
59
60
  "zod": "^4.0.0",
60
- "@theokit/di": "0.2.0"
61
+ "@theokit/di": "0.2.1"
61
62
  },
62
63
  "publishConfig": {
63
64
  "access": "public",
64
65
  "provenance": true
65
66
  },
67
+ "sideEffects": true,
66
68
  "scripts": {
67
69
  "build": "tsup",
68
70
  "typecheck": "tsc --noEmit",