stitchkit 0.95.2 → 0.96.0

package/CHANGELOG.md

@@ -15,6 +15,124 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.96.0] — 2026-09-24
+
+### ⚠️ Breaking changes
+
+**Who must act:** only a project whose tests call a managed resource's phase
+with a context object they wrote by hand — it adds `admission`. Every other
+project raises its range; grammY polling admits updates by batch with no edit.
+
+- `stitchkit/application` — **`ManagedResourceContext` carries the
+  application's admission.** A resource that *fetches* work — a poller, a queue
+  consumer — should not fetch while the application is starting or degraded,
+  and until now reached the handle through a closure over a variable assigned
+  after the graph that contained it. `context.admission`
+  (`ManagedResourceAdmission`) offers `acquire()` and
+  `acquireWhenAccepting(signal)`, which waits and then holds one operation,
+  rejecting on abort and once the application can no longer admit. The kernel
+  supplies it to every phase; a context built by hand in a test must add it:
+
+  ```ts
+  // before
+  resource.close?.({ applicationId, signal, now, reportHealth, use })
+  // after
+  resource.close?.({ applicationId, signal, now, reportHealth, use,
+    admission: { acquire: () => null, acquireWhenAccepting: () => new Promise(() => {}) } })
+  ```
+
+### Added
+
+- `stitchkit/application/grammy` — **`grammyBotResources`**: a long-polling bot
+  as `telegram-configuration` (the application's `configure`, e.g.
+  `setMyCommands`, run before polling on every start) and `telegram-polling`,
+  both after the bot's `dependsOn`, with those stable ids
+  (`TELEGRAM_CONFIGURATION_RESOURCE_ID`, `TELEGRAM_POLLING_RESOURCE_ID`).
+  Three consuming bots each assembled this pair by hand under their own names.
+- `stitchkit/application/grammy` — `onEnded` on `grammyPollingResource` and
+  `grammyBotResources`: called once when polling that was ready ends on its own
+  (401, 409, a rethrowing `bot.catch`), never for a requested stop. grammY's
+  poller does not recover in-process and the framework does not exit processes,
+  so this is the one place an application turns that end into its shutdown.
+- `stitchkit/observability` — **`createJsonLogger`**: the process journal for a
+  bot or worker. One JSON line per call in pino's shape (numeric `level`,
+  epoch `time`, `msg`) on standard output, through `createBoundedLogger`, so an
+  `Error` under any key keeps name, message, stack and cause — a consuming
+  bot's startup failure had reached its journal as `"error":{}` — and secrets
+  are masked. `level`, static `fields`, injectable `write`; `JSON_LOG_LEVELS`
+  names the numbers a line reader matches on (`error` is 50).
+- `stitchkit/telegram` — **`runTelegramBroadcast`**: a broadcast resumable by
+  name. The audience is written once, progress is an append-only journal; a
+  send in flight at a crash is `uncertain` and not repeated; blocked, gone and
+  never-started recipients are `unreachable` and never addressed again; a 429
+  waits Telegram's `retry_after`; a server error is retried up to
+  `maxAttempts`; a message Telegram cannot parse, or Telegram unreachable,
+  halts the run without charging the recipient. Pacing at `ratePerSecond` (25),
+  `dryRun`, one runner per name. `telegramBroadcastSender` is the standard
+  `send` (`sendMessage` or `copyMessage`). Two consuming bots carried the same
+  five-file subsystem with its own refusal phrases.
+- `stitchkit/telegram` — **`createTelegramOperatorChannel`**: the operator's
+  chat, apart from the journal. `post` returns at once and never throws; paced
+  sends into forum topics, 429 honoured, the oldest message dropped on
+  overflow and every drop reported with why; `drain` and `close` for the way
+  down. `telegramOperatorSender` is the standard `send`.
+- `stitchkit/telegram` — **`createTelegramLocalFiles`**: a file the local Bot
+  API server wrote under `<root>/<token>/`. `resolve` and `remove` stay inside
+  the bot's directory — `../`, an absolute path elsewhere and a link pointing
+  out are refused on real paths — and a refusal names a reason, never the path
+  or the token. `check()` for readiness. The recommended root variable is
+  `BOT_API_FILES_ROOT`.
+- `stitchkit/telegram` — `callTelegramBotApi` / `TelegramBotApiError`: one Bot
+  API call over `fetch` whose refusal keeps `error_code`, `description` and
+  `parameters` for `classifyTelegramSendFailure`, and
+  `TELEGRAM_BOT_TOKEN_PATTERN` for a logger's `sensitiveUrlPatterns`.
+- Public-surface ceilings raised for these: `stitchkit/telegram` 9 → 37,
+  `stitchkit/application/grammy` 7 → 13, `stitchkit/observability` 61 → 65,
+  `stitchkit/application` 277 → 278.
+
+### Changed
+
+- `stitchkit/application/grammy` — **`grammyPollingResource` admits updates by
+  batch.** grammY confirms a batch by asking for the next one, whatever its
+  middleware did, so an update that arrived while the application was
+  starting, degraded or stopping was refused and then confirmed as handled —
+  lost on every restart of two consuming bots. The resource now waits for
+  admission before each long poll, returns a batch to grammY only while holding
+  one admission lease for it, and on shutdown finishes that batch before
+  `bot.stop()` confirms the offset. A batch the application will not admit is
+  never returned; Telegram keeps it for the next process.
+- `stitchkit/application/grammy` — `dependsOn` on both grammY resources takes
+  resource objects as well as ids, like every other resource.
+
+### Fixed
+
+- `stitchkit/application/grammy` — a poller that ended on its own is one
+  failure, not two. Its `drain` awaited the ended completion again and failed
+  with the same error, so the shutdown that followed was `forced` and the
+  journal carried a `drain` failure for an end that had already happened. The
+  ended completion is now drained quietly, and `onEnded` runs a macrotask later
+  so the kernel records it as `completion` before an observer's shutdown can
+  mark the application stopping.
+
+## [0.95.3] — 2026-09-23
+
+### Fixed
+
+- `stitchkit/live` — the watch client took a revision as a floor across two
+  lives of the hub. Revisions count one hub's life of a key, so after an API
+  restart the new hub answered the reopen with a `full` value at revision 1
+  and the client dropped it, and every later one, as "no newer" until the new
+  counter passed the old — while showing the key live. The first answer to
+  each `open` is now taken whatever its revision; within one open the
+  counter orders frames as before.
+- `stitchkit/agent-runtime` — a turn total no longer knows more than its
+  steps. `mergeModelTotals` took each field from the SDK aggregate, which the
+  OpenRouter adapter had already summed with `cached_tokens ?? 0`, so a turn
+  whose every request reported no cache figure ended as
+  `{ value: 0, provenance: 'computed' }`. A field every step reported as
+  `unavailable` now stays `unavailable` in the total; an explicit zero and a
+  positive count are kept.
+
 ## [0.95.2] — 2026-09-23
 
 ### Added

package/dist/agent-runtime/runtime-internals.d.ts

@@ -60,6 +60,12 @@ export declare function addUsage(total: AgentUsage | undefined, step: AgentUsage
  * handed us. Which loop did the adding is not a difference a caller filtering
  * for a billable figure cares about, and pretending otherwise made one run
  * report `provider-reported` on success and `computed` on abort.
+ *
+ * A field every step reported as `unavailable` stays `unavailable`: the
+ * aggregate is summed from the SDK's normalized usage, where an adapter may
+ * already have written `cached_tokens ?? 0`, so its zero is the adapter's word
+ * and not the provider's. The OpenRouter adapter did exactly that, and a turn
+ * whose every request said "no cache figure" ended as a confident "cache 0".
  */
 export declare function mergeModelTotals(sdkTotal: AgentUsage, accumulated: AgentUsage | undefined): AgentUsage;
 /**

package/dist/agent-runtime/runtime-internals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-internals.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/runtime-internals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,IAAI,CAAC;AAC7C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,KAAK,gBAAgB,EAGrB,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAChB,MAAM,WAAW,CAAC;AAGnB;;;;;GAKG;AAEH,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAI1E;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAG5E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO;;;;cAI9C;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS;;;EAKhF;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,gBAAgB,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAQxE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,mBAAmB,CAK5E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,EAAE,IAAI,EAAE,UAAU,GAAG,UAAU,CAuDpF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,UAAU,EACpB,WAAW,EAAE,UAAU,GAAG,SAAS,GAClC,UAAU,CAiBZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,CAYrE;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,IAAI,UAAU,CAUzC;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,kBAAkB,GAAG,UAAU,CAmBvE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS;;iBAEhE,IAAI;;;;;;EAgDxB"}
+{"version":3,"file":"runtime-internals.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/runtime-internals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,IAAI,CAAC;AAC7C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,KAAK,gBAAgB,EAGrB,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAChB,MAAM,WAAW,CAAC;AAGnB;;;;;GAKG;AAEH,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAI1E;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAG5E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO;;;;cAI9C;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS;;;EAKhF;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,gBAAgB,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAQxE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,mBAAmB,CAK5E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,EAAE,IAAI,EAAE,UAAU,GAAG,UAAU,CAuDpF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,UAAU,EACpB,WAAW,EAAE,UAAU,GAAG,SAAS,GAClC,UAAU,CAmBZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,CAYrE;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,IAAI,UAAU,CAUzC;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,kBAAkB,GAAG,UAAU,CAmBvE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS;;iBAEhE,IAAI;;;;;;EAgDxB"}

package/dist/application/grammy-bot.d.ts

@@ -0,0 +1,44 @@
+import type { Bot, Context } from 'grammy';
+import { type GrammyPollingEnd, type GrammyPollingResourceConfig } from './grammy.js';
+import { type ManagedResource, type ManagedResourceContext, type ManagedResourceDependency } from './resource.js';
+/** The two ids a monitor, a test and a restart address the bot by. */
+export declare const TELEGRAM_CONFIGURATION_RESOURCE_ID = "telegram-configuration";
+export declare const TELEGRAM_POLLING_RESOURCE_ID = "telegram-polling";
+export interface GrammyBotResourcesConfig<C extends Context> {
+    readonly bot: Bot<C>;
+    /**
+     * What the bot needs before it may say anything to Telegram — the database
+     * its handlers read, the queues they enqueue into, the HTTP server whose
+     * webhooks they answer. Both resources start after all of it.
+     */
+    readonly dependsOn?: readonly ManagedResourceDependency[];
+    /**
+     * Publish what Telegram shows before the first update — the command menu,
+     * the description, the menu button. Runs once per start, before polling, so
+     * a menu that failed to publish fails the start instead of hiding behind a
+     * bot that answers. Omit it and there is no `telegram-configuration`.
+     */
+    readonly configure?: (context: ManagedResourceContext) => void | Promise<void>;
+    readonly polling?: GrammyPollingResourceConfig<C>['polling'];
+    readonly onStart?: GrammyPollingResourceConfig<C>['onStart'];
+    readonly onError?: (error: unknown) => void | Promise<void>;
+    /** See `GrammyPollingResourceConfig.onEnded` — the one place the end of polling is decided. */
+    readonly onEnded?: (end: GrammyPollingEnd) => void | Promise<void>;
+}
+export interface GrammyBotResources {
+    readonly configuration?: ManagedResource;
+    readonly polling: ManagedResource;
+    /** Both, in start order, for `createApplication({ resources })`. */
+    readonly resources: readonly ManagedResource[];
+}
+/**
+ * A long-polling Telegram bot as resources of an application.
+ *
+ * Every bot assembled the same pair by hand — a configuration resource calling
+ * `setMyCommands`, then `grammyPollingResource` — under its own names, and only
+ * one of them held updates back while the application was not ready. One call
+ * now gives the pair with stable ids, updates admitted by batch, and the end of
+ * polling reported to one callback.
+ */
+export declare function grammyBotResources<C extends Context>(config: GrammyBotResourcesConfig<C>): GrammyBotResources;
+//# sourceMappingURL=grammy-bot.d.ts.map

package/dist/application/grammy-bot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammy-bot.d.ts","sourceRoot":"","sources":["../../src/application/grammy-bot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,2BAA2B,EAEjC,MAAM,UAAU,CAAC;AAClB,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC/B,MAAM,YAAY,CAAC;AAEpB,sEAAsE;AACtE,eAAO,MAAM,kCAAkC,2BAA2B,CAAC;AAC3E,eAAO,MAAM,4BAA4B,qBAAqB,CAAC;AAE/D,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,OAAO;IACzD,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC1D;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,2BAA2B,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,2BAA2B,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,eAAe,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,oEAAoE;IACpE,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;CAChD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,OAAO,EAClD,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAClC,kBAAkB,CA0BpB"}

package/dist/application/grammy-update-admission.d.ts

@@ -0,0 +1,35 @@
+import type { Bot, Context } from 'grammy';
+import type { ManagedResourceAdmission } from './resource.js';
+/**
+ * Updates reach grammY only while the application admits them.
+ *
+ * grammY's built-in polling acknowledges a batch by asking for the next one
+ * with a higher offset, and it asks as soon as the previous batch has been
+ * through middleware — whatever the middleware did with it. So an update that
+ * arrived while the application was starting, degraded or stopping was handed
+ * to a handler that refused it, and the next `getUpdates` confirmed it to
+ * Telegram as handled. Nothing retried it; it was simply gone.
+ *
+ * The gate sits on the one call that moves the offset. Before asking for a
+ * batch it waits until the application admits; after Telegram answers with a
+ * non-empty batch it takes one admission lease for the whole batch and only
+ * then returns it to grammY. grammY handles a batch sequentially and asks for
+ * the next one only when it is done, so the next `getUpdates` is also the
+ * moment the batch is finished and its lease is released — no middleware, and
+ * so no dependence on where in the chain it was registered.
+ *
+ * A batch that arrives when the application will not admit it is never
+ * returned: the request fails with an abort, grammY's offset does not move, and
+ * Telegram keeps the updates for the next process.
+ */
+export interface UpdateAdmissionGate {
+    /** Admission for the current life of the polling resource; `undefined` passes calls through. */
+    bind(admission: ManagedResourceAdmission | undefined): void;
+    /** Resolves when no admitted batch is in progress, or when `signal` aborts. */
+    whenIdle(signal: AbortSignal): Promise<void>;
+    /** Release an admitted batch whose handling ended without a next request. */
+    release(): void;
+}
+/** Install the gate once per bot; a restarted resource binds the same gate again. */
+export declare function updateAdmissionGate<C extends Context>(bot: Bot<C>): UpdateAdmissionGate;
+//# sourceMappingURL=grammy-update-admission.d.ts.map

package/dist/application/grammy-update-admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammy-update-admission.d.ts","sourceRoot":"","sources":["../../src/application/grammy-update-admission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAE3C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,mBAAmB;IAClC,gGAAgG;IAChG,IAAI,CAAC,SAAS,EAAE,wBAAwB,GAAG,SAAS,GAAG,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAAC;CACjB;AAsDD,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAmDvF"}

package/dist/application/grammy.d.ts

@@ -1,22 +1,41 @@
 import { type Bot, Context, type PollingOptions, type WebhookReplyEnvelope } from 'grammy';
 import { AppError } from '../contract/errors.js';
-import { type ManagedResource } from './resource.js';
+import { type ManagedResource, type ManagedResourceDependency } from './resource.js';
 export interface GrammyPollingResourceConfig<C extends Context> {
     readonly id: string;
     readonly bot: Bot<C>;
-    readonly dependsOn?: readonly string[];
+    readonly dependsOn?: readonly ManagedResourceDependency[];
     readonly required?: boolean;
     readonly polling?: Omit<PollingOptions, 'onStart'>;
     readonly onStart?: PollingOptions['onStart'];
     readonly onError?: (error: unknown) => void | Promise<void>;
+    /**
+     * Polling ended on its own after it was ready — Telegram refused the token,
+     * another process took the same bot (409), or the error handler rethrew.
+     * Called once, never for a stop the application asked for. grammY's poller
+     * does not recover in-process, and the framework does not exit processes
+     * (ADR 0074): this is where an application turns the end into its shutdown.
+     */
+    readonly onEnded?: (end: GrammyPollingEnd) => void | Promise<void>;
 }
-/** Thin lifecycle adapter for grammY's built-in long polling. */
+/** How a poller that was ready came to an end; `error` is absent when it simply returned. */
+export interface GrammyPollingEnd {
+    readonly error?: unknown;
+}
+/**
+ * Lifecycle adapter for grammY's built-in long polling.
+ *
+ * Updates are admitted by batch (see `grammy-update-admission`): no batch is
+ * fetched while the application is not accepting, and the batch in hand is
+ * finished before `bot.stop()` confirms the offset, so a stop neither loses an
+ * update nor hands the next process one this process already handled.
+ */
 export declare function grammyPollingResource<C extends Context>(config: GrammyPollingResourceConfig<C>): ManagedResource;
 export type GrammyUpdate<C extends Context = Context> = Parameters<Bot<C>['handleUpdate']>[0];
 export interface GrammyWebhookResourceConfig<C extends Context> {
     readonly id: string;
     readonly bot: Bot<C>;
-    readonly dependsOn?: readonly string[];
+    readonly dependsOn?: readonly ManagedResourceDependency[];
     readonly required?: boolean;
     readonly onError?: (error: unknown) => void | Promise<void>;
 }

package/dist/application/grammy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grammy.d.ts","sourceRoot":"","sources":["../../src/application/grammy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC3F,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAMzE,MAAM,WAAW,2BAA2B,CAAC,CAAC,SAAS,OAAO;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAcD,iEAAiE;AACjE,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,OAAO,EACrD,MAAM,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACrC,eAAe,CAiEjB;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9F,MAAM,WAAW,2BAA2B,CAAC,CAAC,SAAS,OAAO;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC,SAAS,OAAO;IACtD,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,YAAY,CACV,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EACvB,oBAAoB,CAAC,EAAE,oBAAoB,GAC1C,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAaD;;;;;;;;;;;GAWG;AACH,qBAAa,6BAA8B,SAAQ,QAAQ,CAAC,8BAA8B,CAAC;IACzF,cAOC;CACF;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,OAAO,EAC3D,MAAM,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACrC,qBAAqB,CAAC,CAAC,CAAC,CAiE1B"}
+{"version":3,"file":"grammy.d.ts","sourceRoot":"","sources":["../../src/application/grammy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC3F,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC/B,MAAM,YAAY,CAAC;AAMpB,MAAM,WAAW,2BAA2B,CAAC,CAAC,SAAS,OAAO;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,6FAA6F;AAC7F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAgCD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,OAAO,EACrD,MAAM,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACrC,eAAe,CA4EjB;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9F,MAAM,WAAW,2BAA2B,CAAC,CAAC,SAAS,OAAO;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC,SAAS,OAAO;IACtD,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,YAAY,CACV,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EACvB,oBAAoB,CAAC,EAAE,oBAAoB,GAC1C,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAaD;;;;;;;;;;;GAWG;AACH,qBAAa,6BAA8B,SAAQ,QAAQ,CAAC,8BAA8B,CAAC;IACzF,cAOC;CACF;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,OAAO,EAC3D,MAAM,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACrC,qBAAqB,CAAC,CAAC,CAAC,CAiE1B"}

package/dist/application/kernel-admission.d.ts

@@ -5,4 +5,15 @@ export declare function acquire(state: KernelState): ApplicationOperationLease |
 export declare function run<T>(state: KernelState, work: () => T | Promise<T>): Promise<T>;
 /** Resolves once every admitted operation has released its lease. */
 export declare function waitForPending(state: KernelState): Promise<void>;
+/**
+ * Wait until the application admits, then admit one operation.
+ *
+ * For the resource that brings work in rather than the caller that is handed
+ * it: a poller asking Telegram for the next batch has nothing to refuse — the
+ * right move while the application is starting or degraded is to not ask yet.
+ * Rejects with the signal's reason once it aborts, and with
+ * `ApplicationAdmissionError` once the application can no longer admit at all,
+ * so a waiter never outlives the lifetime it was waiting on.
+ */
+export declare function acquireWhenAccepting(state: KernelState, signal: AbortSignal): Promise<ApplicationOperationLease>;
 //# sourceMappingURL=kernel-admission.d.ts.map

package/dist/application/kernel-admission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kernel-admission.d.ts","sourceRoot":"","sources":["../../src/application/kernel-admission.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAC9F,OAAO,EAAW,KAAK,WAAW,EAAW,MAAM,gBAAgB,CAAC;AAEpE,gFAAgF;AAChF,wBAAgB,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,yBAAyB,GAAG,IAAI,CAsB5E;AAED,wBAAsB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAQvF;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhE"}
+{"version":3,"file":"kernel-admission.d.ts","sourceRoot":"","sources":["../../src/application/kernel-admission.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAC9F,OAAO,EAAW,KAAK,WAAW,EAAW,MAAM,gBAAgB,CAAC;AAEpE,gFAAgF;AAChF,wBAAgB,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,yBAAyB,GAAG,IAAI,CAsB5E;AAED,wBAAsB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAQvF;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,yBAAyB,CAAC,CA+CpC"}

package/dist/application/kernel-resource-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kernel-resource-context.d.ts","sourceRoot":"","sources":["../../src/application/kernel-resource-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAEhB,KAAK,cAAc,EAEpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAEV,sBAAsB,EAEvB,MAAM,YAAY,CAAC;AAEpB,oFAAoF;AACpF,wBAAgB,UAAU,CACxB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAO,GACpF,sBAAsB,CAmDxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAC3B,IAAI,CAYN"}
+{"version":3,"file":"kernel-resource-context.d.ts","sourceRoot":"","sources":["../../src/application/kernel-resource-context.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,WAAW,EAEhB,KAAK,cAAc,EAEpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAEV,sBAAsB,EAEvB,MAAM,YAAY,CAAC;AAEpB,oFAAoF;AACpF,wBAAgB,UAAU,CACxB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAO,GACpF,sBAAsB,CAuDxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAC3B,IAAI,CAYN"}

package/dist/application/resource.d.ts

@@ -1,3 +1,4 @@
+import type { ApplicationOperationLease } from './kernel-contract.js';
 import type { ApplicationHealth } from './schemas.js';
 /**
  * What a resource declares it must start after.
@@ -45,9 +46,30 @@ export type ManagedResourcePublished<TResource> = TResource extends {
 }> extends {
     value: infer TValue;
 } ? TValue : ManagedResourcePublishesNoValue : ManagedResourcePublishesNoValue;
+/**
+ * The application's admission, as a resource that brings work in sees it.
+ *
+ * A caller handed work — an HTTP request, a webhook update — asks once and is
+ * refused. A resource that *fetches* work — a poller, a queue consumer — has a
+ * better move while the application is starting or degraded: not to fetch yet.
+ * Without this, such a resource reached for the application handle through a
+ * closure over a variable assigned after the graph that contains it.
+ */
+export interface ManagedResourceAdmission {
+    /** Admit one operation now, or `null` while the application is not accepting. */
+    acquire(): ApplicationOperationLease | null;
+    /**
+     * Admit one operation as soon as the application accepts. Rejects with the
+     * signal's reason on abort, and with `ApplicationAdmissionError` once the
+     * application is shutting down or failed, since it will not admit again.
+     */
+    acquireWhenAccepting(signal: AbortSignal): Promise<ApplicationOperationLease>;
+}
 export interface ManagedResourceContext {
     readonly applicationId: string;
     readonly signal: AbortSignal;
+    /** The application's operation admission — see `ManagedResourceAdmission`. */
+    readonly admission: ManagedResourceAdmission;
     readonly deadlineAt?: number;
     readonly forceDeadlineAt?: number;
     now(): number;

package/dist/application/resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/application/resource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,eAAe,CAAC;AAEjE;;;;;;;;GAQG;AACH,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,uDAAuD,EAAE,KAAK,CAAC;CACzE;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,wBAAwB,CAAC,SAAS,IAAI,SAAS,SAAS;IAClE,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,GAAG,MAAM,MAAM,CAAC;CACrC,GACG,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC5D,+BAA+B,GAC/B,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,MAAM,CAAA;CAAE,GAC1E,MAAM,GACN,+BAA+B,GACnC,+BAA+B,CAAC;AAEpC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,GAAG,IAAI,MAAM,CAAC;IACd,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,iBAAiB,EAAE,SAAS,CAAC,GAAG,IAAI,CAAC;IAClE;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,SAAS,SAAS,eAAe,EACnC,QAAQ,EAAE,SAAS,GAClB,wBAAwB,CAAC,SAAS,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,0BAA0B;IACzC,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,KAAK,CACH,OAAO,EAAE,sBAAsB,GAE7B,IAAI,GACJ,0BAA0B,GAC1B,OAAO,CAAC,IAAI,CAAC,GACb,OAAO,CAAC,0BAA0B,GAAG,SAAS,CAAC,CAAC;IACpD,kEAAkE;IAClE,QAAQ,CAAC,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,aAAa,CAAC,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,KAAK,CAAC,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,gFAAgF;IAChF,KAAK,CAAC,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,KAAK,CAAC,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAED,kDAAkD;AAClD,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,yBAAyB,GAAG,MAAM,CAEzF;AAED,wBAAgB,qBAAqB,CAAC,KAAK,CAAC,SAAS,SAAS,eAAe,EAC3E,QAAQ,EAAE,SAAS,GAClB,SAAS,CAEX"}
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/application/resource.ts"],"names":[],"mappings":"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"}

package/dist/entrypoints/agent-runtime/harness.js

@@ -6,7 +6,7 @@ import {
   composeAgentPrompt,
   createAgentRuntime,
   createAgentRuntimeEventSink
-} from "../../index-8zja4pkf.js";
+} from "../../index-nts4a2br.js";
 import"../../index-83bdg97s.js";
 import"../../index-y64k3s0h.js";
 import {

package/dist/entrypoints/agent-runtime.js

@@ -24,7 +24,7 @@ import {
   renderAgentStateSlots,
   repairedSearchCall,
   selectAgentHistory
-} from "../index-8zja4pkf.js";
+} from "../index-nts4a2br.js";
 import"../index-83bdg97s.js";
 import {
   AgentAdmissionEventSchema,

package/dist/entrypoints/application/grammy.d.ts

@@ -1,2 +1,3 @@
-export { createGrammyWebhookResource, type GrammyPollingResourceConfig, type GrammyUpdate, type GrammyWebhookResource, type GrammyWebhookResourceConfig, GrammyWebhookUnavailableError, grammyPollingResource, } from '../../application/grammy.js';
+export { createGrammyWebhookResource, type GrammyPollingEnd, type GrammyPollingResourceConfig, type GrammyUpdate, type GrammyWebhookResource, type GrammyWebhookResourceConfig, GrammyWebhookUnavailableError, grammyPollingResource, } from '../../application/grammy.js';
+export { type GrammyBotResources, type GrammyBotResourcesConfig, grammyBotResources, TELEGRAM_CONFIGURATION_RESOURCE_ID, TELEGRAM_POLLING_RESOURCE_ID, } from '../../application/grammy-bot.js';
 //# sourceMappingURL=grammy.d.ts.map

package/dist/entrypoints/application/grammy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grammy.d.ts","sourceRoot":"","sources":["../../../src/entrypoints/application/grammy.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,KAAK,2BAA2B,EAChC,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,6BAA6B,EAC7B,qBAAqB,GACtB,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"grammy.d.ts","sourceRoot":"","sources":["../../../src/entrypoints/application/grammy.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,KAAK,gBAAgB,EACrB,KAAK,2BAA2B,EAChC,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,6BAA6B,EAC7B,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,kBAAkB,EAClB,kCAAkC,EAClC,4BAA4B,GAC7B,MAAM,8BAA8B,CAAC"}

package/dist/entrypoints/application/grammy.js

@@ -7,6 +7,91 @@ import {
 
 // src/application/grammy.ts
 import { Context } from "grammy";
+
+// src/application/grammy-update-admission.ts
+function batchSize(result) {
+  return Array.isArray(result) ? result.length : 0;
+}
+function abortError() {
+  return new DOMException("Telegram polling stopped", "AbortError");
+}
+function untilAborted(signal) {
+  return new Promise((_, reject) => {
+    if (signal.aborted)
+      reject(abortError());
+    else
+      signal.addEventListener("abort", () => reject(abortError()), { once: true });
+  });
+}
+async function admitted(admission, signal) {
+  try {
+    return await admission.acquireWhenAccepting(signal);
+  } catch {
+    if (signal.aborted)
+      throw abortError();
+    return untilAborted(signal);
+  }
+}
+function followed(signal) {
+  const controller = new AbortController;
+  if (signal.aborted)
+    controller.abort(abortError());
+  else
+    signal.addEventListener("abort", () => controller.abort(abortError()));
+  return controller.signal;
+}
+var gates = new WeakMap;
+function updateAdmissionGate(bot) {
+  const existing = gates.get(bot);
+  if (existing)
+    return existing;
+  let admission;
+  let batch;
+  const idle = new Set;
+  const release = () => {
+    batch?.release();
+    batch = undefined;
+    for (const waiter of idle)
+      waiter();
+    idle.clear();
+  };
+  bot.api.config.use(async (previous, method, payload, signal) => {
+    if (method !== "getUpdates" || !signal || !admission) {
+      return previous(method, payload, signal);
+    }
+    release();
+    const polling = admission;
+    const stopped = followed(signal);
+    (await admitted(polling, stopped)).release();
+    const answer = await previous(method, payload, signal);
+    if (answer.ok && batchSize(answer.result) > 0)
+      batch = await admitted(polling, stopped);
+    return answer;
+  });
+  const gate = {
+    bind(next) {
+      admission = next;
+    },
+    whenIdle(signal) {
+      if (!batch || signal.aborted)
+        return Promise.resolve();
+      return new Promise((resolve) => {
+        const done = () => {
+          signal.removeEventListener("abort", done);
+          idle.delete(done);
+          resolve();
+        };
+        idle.add(done);
+        signal.addEventListener("abort", done, { once: true });
+      });
+    },
+    release
+  };
+  gates.set(bot, gate);
+  return gate;
+}
+
+// src/application/grammy.ts
 if (typeof Context !== "function") {
   throw new TypeError("[stitchkit] stitchkit/application/grammy requires the grammY peer");
 }
@@ -15,7 +100,15 @@ function reportIsolated(callback, error) {
     return;
   Promise.resolve().then(() => callback(error)).catch(() => {});
 }
+function reportEnd(callback, end) {
+  if (!callback)
+    return;
+  setTimeout(() => {
+    Promise.resolve().then(() => callback(end)).catch(() => {});
+  }, 0);
+}
 function grammyPollingResource(config) {
+  const gate = updateAdmissionGate(config.bot);
   let completion;
   let stopPromise;
   const stop = () => {
@@ -29,7 +122,9 @@ function grammyPollingResource(config) {
     id: config.id,
     ...config.dependsOn && { dependsOn: config.dependsOn },
     ...config.required !== undefined && { required: config.required },
-    start() {
+    start(context) {
+      stopPromise = undefined;
+      gate.bind(context.admission);
       let resolveReady = () => {
         return;
       };
@@ -50,13 +145,18 @@ function grammyPollingResource(config) {
         }
       });
       completion = polling.then(() => {
+        gate.release();
         if (!becameReady) {
           rejectReady(new Error("[stitchkit] grammY polling stopped before reaching readiness"));
-        }
+        } else if (!stopPromise)
+          reportEnd(config.onEnded, {});
       }, (error) => {
+        gate.release();
         if (!becameReady)
           rejectReady(error);
         reportIsolated(config.onError, error);
+        if (becameReady && !stopPromise)
+          reportEnd(config.onEnded, { error });
         throw error;
       });
       completion.catch(() => {
@@ -64,11 +164,14 @@ function grammyPollingResource(config) {
       });
       return { ready, completion };
     },
-    stopAdmission() {
-      return stop();
+    async stopAdmission(context) {
+      await gate.whenIdle(context.signal);
+      await stop();
     },
     async drain() {
-      await completion;
+      await completion?.catch(() => {
+        return;
+      });
     },
     async close() {
       await stop();
@@ -162,8 +265,39 @@ function createGrammyWebhookResource(config) {
     }
   };
 }
+// src/application/grammy-bot.ts
+var TELEGRAM_CONFIGURATION_RESOURCE_ID = "telegram-configuration";
+var TELEGRAM_POLLING_RESOURCE_ID = "telegram-polling";
+function grammyBotResources(config) {
+  const dependsOn = config.dependsOn ?? [];
+  const configure = config.configure;
+  const configuration = configure ? defineManagedResource({
+    id: TELEGRAM_CONFIGURATION_RESOURCE_ID,
+    dependsOn,
+    async start(context) {
+      await configure(context);
+    }
+  }) : undefined;
+  const polling = grammyPollingResource({
+    id: TELEGRAM_POLLING_RESOURCE_ID,
+    bot: config.bot,
+    dependsOn: configuration ? [configuration] : dependsOn,
+    ...config.polling && { polling: config.polling },
+    ...config.onStart && { onStart: config.onStart },
+    ...config.onError && { onError: config.onError },
+    ...config.onEnded && { onEnded: config.onEnded }
+  });
+  return {
+    ...configuration && { configuration },
+    polling,
+    resources: configuration ? [configuration, polling] : [polling]
+  };
+}
 export {
   grammyPollingResource,
+  grammyBotResources,
   createGrammyWebhookResource,
+  TELEGRAM_POLLING_RESOURCE_ID,
+  TELEGRAM_CONFIGURATION_RESOURCE_ID,
   GrammyWebhookUnavailableError
 };

package/dist/entrypoints/application.d.ts

@@ -13,7 +13,7 @@ export { type ApplicationSnapshotSink, type ApplicationSnapshotSinkConfig, type
 export { createNotificationOutbox, type DroppedNotification, type EnqueueNotification, type NotificationFailureClassification, type NotificationOutbox, type NotificationOutboxConfig, type NotificationOutboxItem, type NotificationOutboxReceipt, type NotificationOutboxResource, type NotificationOutboxResourceConfig, type NotificationOutboxState, type NotificationSend, notificationOutboxResource, notificationOutboxStateSchema, } from '../application/notification-outbox.js';
 export { createProcessLifecycleLedger, type LifecycleLedgerResource, type LifecycleLedgerResourceConfig, lifecycleLedgerResource, type ProcessLifecycleLedger, type ProcessLifecycleLedgerConfig, } from '../application/process-lifecycle.js';
 export { type DrainingFact, type LifecycleRun, LifecycleRunSchema, type LifecycleState, LifecycleStateSchema, type LifecycleTermination, LifecycleTerminationSchema, type LifecycleTransition, type PreviousExit, PreviousExitSchema, type ProcessLifecycleFact, type ReadyFact, type SameVersionOverlap, type ShutdownFact, type StartFact, type TransitionRunInput, type TransitionShutdownInput, type TransitionStartInput, transitionProcessDraining, transitionProcessReady, transitionProcessShutdown, transitionProcessStart, } from '../application/process-lifecycle-transitions.js';
-export { defineManagedResource, type ManagedResource, type ManagedResourceContext, type ManagedResourceDependency, type ManagedResourcePublished, type ManagedResourcePublishesNoValue, type ManagedResourceStartResult, managedResourceDependencyId, } from '../application/resource.js';
+export { defineManagedResource, type ManagedResource, type ManagedResourceAdmission, type ManagedResourceContext, type ManagedResourceDependency, type ManagedResourcePublished, type ManagedResourcePublishesNoValue, type ManagedResourceStartResult, managedResourceDependencyId, } from '../application/resource.js';
 export { createRevisionSignal, type RevisionSignal, type RevisionSignalAdvanceResult, RevisionSignalAdvanceResultSchema, type RevisionSignalClock, type RevisionSignalConfig, type RevisionSignalSnapshot, RevisionSignalSnapshotSchema, type RevisionSignalState, RevisionSignalStateSchema, type RevisionSignalTimer, type RevisionSignalWaitOptions, type RevisionSignalWaitOutcome, RevisionSignalWaitOutcomeSchema, type RevisionSignalWaitResult, RevisionSignalWaitResultSchema, } from '../application/revision-signal.js';
 export { createManagedSchedule, type ManagedSchedule, type ManagedScheduleClock, type ManagedScheduleConfig, type ManagedScheduleDescriptor, ManagedScheduleDescriptorSchema, type ManagedScheduleErrorPolicy, ManagedScheduleErrorPolicySchema, type ManagedScheduleOverlap, ManagedScheduleOverlapSchema, type ManagedScheduleRunContext, type ManagedScheduleStatus, ManagedScheduleStatusSchema, type ManagedScheduleTimer, } from '../application/schedule.js';
 export { type ManagedServerResource, type ManagedServerResourceConfig, managedServerResource, } from '../application/server-resource.js';