@vibesdotdev/external 0.0.0-stage → 1.0.0-rc.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 VIBES DEV LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# @vibesdotdev/external
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+External tool manifest contracts and adapters for integrating non-Vibes tools.
+
+This package is part of the public Vibes framework package set. The source repository is private while the public repository split is being prepared, so package documentation is published on the Vibes docs site.
+
+## What it owns
+
+The vendor-neutral external-host concepts: the `external/host` runtime kind and its
+manifests, the canonical `ExternalClient`, MCP, hook, plugin and skill projection
+for any external tool, the shared JSON-RPC session stack and host harness, the
+ambient agent-awareness records, and the `vibes dev external` CLI. Each concrete
+host (editor, agent CLI, IDE) lives in its own integration package that registers
+into these concepts. Vibes-hosted behavior is reached through the runtime, never
+baked in here.
+
+## Install
+
+```sh
+bun add @vibesdotdev/external
+# or
+npm install @vibesdotdev/external
+```
+
+## CLI (consumer)
+
+| Command                                             | Purpose                                                                                                            |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `vibes dev external <host> <operation>`             | Run a provider operation discovered from the live runtime, such as `pi install`                                    |
+| `vibes dev external status`                         | Detect installed hosts                                                                                             |
+| `vibes dev external presets list`                   | Host aliases + profiles (`mcp`, `plugin`, `hooks`, …)                                                              |
+| `vibes dev external presets apply <host> <profile>` | e.g. `apply claude mcp`, `apply opencode plugin`, `apply cursor skills`                                            |
+| `vibes dev external skills generate codex --global` | Compose registered `tools/skill` descriptors (agents + prompts + tools) into Codex's global Agent Skills directory |
+| `vibes dev external skills generate cursor`         | Generate descriptor-backed skills + Cursor rules when the Cursor adapter is loaded                                 |
+| `vibes dev external hooks call <event>`             | Unified hook handler; tier checks when `collaboration.toolTiers.enabled` is set                                              |
+
+## Ambient agent awareness
+
+Agents working in the same tree see each other's file touches and can message each other. No enforcement — ephemeral knowledge delivered at the moment it matters. The tool and drain subscriptions are active by default; watcher coverage requires explicit activation:
+
+- `external.file-access.ambient` — tool path (fires on `workspace-fs` afterExecute)
+- `external.file-access.ambient-fs` — disabled in production. Before re-enablement, Workspace must stop publishing gone paths and exclude `.vibes/`. Disposable fixtures explicitly enable it and dispatch the Filesystem event through the registered subscription.
+- `external.file-access.ambient-drain` — delivers queued notices on any MCP tool call
+
+See [docs/architecture/AMBIENT-AGENT-AWARENESS.md](../docs/architecture/AMBIENT-AGENT-AWARENESS.md) for the full design.
+
+`vibes who` — live roster of agents active on this machine.
+
+## Documentation
+
+- Package guide: https://docs.vibes.dev/external
+- Vibes docs: https://docs.vibes.dev
+- Agent pack IR: `@vibesdotdev/external/consumer/node/pack`
+- Host manifest read API: `@vibesdotdev/external/consumer/node/manifests` (manifests come from integrations plugins)
+- Shared host harness: `@vibesdotdev/external/harness`; Node runtime host: `@vibesdotdev/external/consumer/node/harness` (`VibesAgentHost` and settings plugin).
+
+## Runtime lifetime and delivery
+
+External’s registered `ExternalClient` owns ambient fallback identities, projection batching, collision deduplication, machine/checkout identity caches, ordered pending batches, delivery paths, and retention/roster scheduling state. Activate the plugin before producing ambient events; pass the same runtime to producers and consumers. Kernel resolution owns client identity. `resetExternalClient(runtime)` preserves its former cache-only semantics and never deletes stored data; dispose the owning runtime to end its resources. Identity and dedupe reset helpers affect only that runtime. Machine identity is cached for its lifetime; checkout identity refreshes after two seconds, while participant/work metadata is read on each touch. Standalone identity reads remain best-effort without retaining a cache.
+
+Retention and roster operations remain busy until the underlying work settles, including after a bounded wait times out. The runtime owns cancellation, deadline diagnostics, and finalization joins.
+
+Detached `tool.after` hooks count successful edits and retain their paths. Multiple nonempty claims remain queued in order until a result can carry them. Messages and watcher notices reach the participant once on an observable prompt or stop response. Review cadence uses real Session seats and stored participant counts. Skill generation composes registered `tools/skill` descriptors by default; `includeTools: true` explicitly enables per-tool projection, and dry-run previews the same selection.
+
+Isolation uses `@vibesdotdev/agents/execution`. Failed-provision recovery currently survives only when the remote workspace refuses Agents’ forced purge; unconditional recovery preservation remains an Agents prerequisite. See [the owner evidence and required repair](SPEC.md#isolation-recovery-prerequisite).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/REFERENCE.md

@@ -0,0 +1,217 @@
+# External host reference
+
+Every host a Vibes runtime can project into, and what that host can express.
+Each host is an *external harness*: a process that loads the user's own runtime
+and asks it what it holds, rather than importing descriptors or shelling out.
+
+The pattern is the same everywhere:
+
+```
+host entry → boot the runtime through the kernel's one entry → query the kernel
+           → register what the host can express
+```
+
+What varies per host is the middle question: **what can this host actually
+express?** A host that cannot run a `cli/command` is not offered one. That rule
+is why this document is a capability census rather than a projection spec.
+
+| Reference | Host | Vibes package |
+| --- | --- | --- |
+| [`integrations/opencode/REFERENCE.md`](../../integrations/integrations/opencode/REFERENCE.md) | OpenCode 1.x / 2.x | `@vibesdotdev/integrations-opencode` |
+| [`integrations/pi/REFERENCE.md`](../../integrations/integrations/pi/REFERENCE.md) | Pi | `@vibesdotdev/integrations-pi` |
+| [`MCP`](#mcp) | Any MCP client | `@vibesdotdev/mcp` |
+| [`ACP`](#acp) | Any ACP client | `@vibesdotdev/external/acp` |
+
+## What a Vibes runtime offers
+
+From `RUNTIME-REFERENCE.md`, in consumer scope, a projection can query:
+
+| Kind | Count in this workspace | Enumerable | Invokable |
+| --- | ---: | :---: | :---: |
+| `tools/tool` | 127 | yes | yes |
+| `cli/command` | 786 | yes | yes |
+| `cli/group` | 167 | yes | no |
+| `prompts/manifest` | 35 | yes | via `render` |
+| `ai/provider` | 40 | yes | no |
+| `ai/model` | 103 | yes | no |
+| `diagnostics/check` | 1388 | yes | yes |
+| `docs/topic` | 276 | yes | yes |
+| `storage/manifest` | 71 | yes | yes |
+| `runtime/client` | 58 | yes | yes |
+| `config/manifest` | 114 | yes | yes |
+| `workers/job` | 71 | yes | yes |
+| `pm/command` | 38 | yes | yes |
+| `runbook` | 45 | yes | yes |
+| `rules/rule` | 126 | yes | yes |
+| `external/host` | 8 | yes | no |
+| `external/operation` | 24 | yes | yes |
+| `external/preset` | 18 | yes | yes |
+
+Those are live numbers from one boot, not a catalogue: they change with the
+workspace's `vibes.config`. Run `vibes runtime export` to read the current set.
+
+**Enumerable** means `runtime.query(kind).enabled().descriptors()` lists them
+without loading an implementation. **Invokable** means resolving the descriptor
+gives something callable. A host maps what it can express; a host with no
+equivalent for a kind maps nothing.
+
+## Harness families
+
+Not every `integrations/*` package is an agent host. They fall into three
+groups, and confusing them is how a provider integration ends up pretending to
+be a host adapter.
+
+### Agent hosts — load a runtime, project a capability
+
+These boot a runtime inside their own process and register what it holds.
+
+| Host | Shape | Maps |
+| --- | --- | --- |
+| **OpenCode** | plugin (`tool` map, hooks, `config`) | `tools/tool`, `prompts/manifest`, `ai/provider`, `ai/model` |
+| **Pi** | extension (factory + `ExtensionAPI`) | `tools/tool`, `cli/command`, `prompts/manifest` |
+| **MCP** | stdio/HTTP server | `tools/tool` |
+| **ACP** | session protocol | `tools/tool`, agent execution |
+
+A host also declares a **provider** when it has a provider registry, and a
+**model** when it has a model catalog. OpenCode has both: `config.provider[id]`
+and `config.provider[id].models[id]`, whose fields are all optional, so a model
+the runtime knows little about still projects as the identity facts it has. The
+v2 channel's `catalog.model` is the one surface here that does **not** map:
+`ModelV2Info` requires `api`, `request`, `time.released`, `limit.context`,
+`limit.output` and `status`, none of which a portable capability record
+publishes.
+
+### Configuration projections — write a file, load nothing
+
+These generate a config file a host reads at startup. They never boot a runtime,
+because their output is consumed by another process.
+
+| Host | Writes |
+| --- | --- |
+| `cursor` | project rules; skill composition delegated to `@vibesdotdev/tools` |
+| `ide` | Cline, Continue, Windsurf, Zed projections |
+| `vscode-copilot` | Copilot chat-mode configuration |
+| `hermes` | the Hermes host projection |
+| `aider` | the aider host projection |
+| `gemini` | Gemini CLI configuration plus provider assets |
+| `grok` | xAI provider assets and the Grok Build wire spec |
+| `vibes` | the Vibes service catalog and virtual models |
+
+### Provider integrations — assets on neutral kinds
+
+These contribute `ai/provider`, `ai/model`, `ai/transport` and
+`external/preset` descriptors. They are not hosts and hold no runtime.
+
+`anthropic`, `openai` (Codex), `google`, `mistral`, `groq`, `fireworks`,
+`together`, `openrouter`, `ollama`, `omlx`, `mlx`, `meta`, `zai`, `lmstudio`,
+`cloudflare`, `digitalocean`, and the rest of the provider set.
+
+The distinction matters: **Framework owns neutral kinds; a provider integration
+owns its own vendor identity.** A provider package must never appear in a host
+adapter's kind list, because a host adapter must work with whichever providers
+its workspace composed.
+
+## MCP
+
+MCP is the vendor-neutral tool surface, and the one most hosts can consume
+without a bespoke adapter.
+
+- **Package**: `@vibesdotdev/mcp`, over `@vibesdotdev/tools` for the catalog.
+- **Transports**: stdio and HTTP, with OAuth discovery.
+- **What it exposes**: the runtime's `tools/tool` registry, plus optional
+  Vibes-owned cloud tools (`required-cloud-tools`).
+- **Why it matters here**: a host with no Vibes plugin API can still reach the
+  runtime through MCP. That is the fallback shape, not the preferred one — Pi
+  deliberately dropped MCP for a direct in-process runtime.
+
+## ACP
+
+ACP (Agent Client Protocol) is how an IDE or another agent client talks to a
+Vibes agent.
+
+```ts
+// @vibesdotdev/external/acp
+export function acpRuntimeScope(): Pick<RuntimeScope, 'surface' | 'purpose'>;
+export function runAcpSession<T>(runtime: VibesRuntime, sessionId: string, fn: () => T): T;
+```
+
+An ACP host declares `surface: 'agent'`, `purpose: 'agent'` before boot, and
+hands the runtime over. Session identity is per invocation
+(`actor.harness = 'acp'`, `harnessSessionId`), never a declared scope qualifier.
+ACP lives in External beside the other projection mechanisms; third-party ACP
+**server processes** stay with PM.
+
+## The mapping matrix
+
+One row per kind a projection might want, one column per host, and — where a
+kind does not map — the reason. The reason is the point: a reader who knows *why*
+a surface is absent can tell the difference between "not implemented yet" and
+"the host cannot express it".
+
+| Kind | OpenCode | Pi | MCP | ACP |
+| --- | --- | --- | --- | --- |
+| `tools/tool` | `tool` map | `registerTool` | server tools | session tools |
+| `cli/command` | — prompt template only | `registerCommand` | — | — |
+| `prompts/manifest` | system transform | `before_agent_start` | — | — |
+| `ai/provider` | `config.provider[id]` | `registerProvider` | — | — |
+| `ai/model` | `config.provider[id].models[id]` | — selection, not a catalog | — | — |
+| `agents` | — no roster surface | — no roster surface | — | — |
+| `runtime/event` | `event` hook | `pi.on` | — | — |
+| `diagnostics/check` | — | — | — | — |
+| `storage/*` | — | — | — | — |
+
+Why each absence:
+
+- **`cli/command` in OpenCode.** `config.command` is `{ template, description?,
+  agent?, model? }` — a prompt template, not an executable the host invokes. The
+  only command hooks are `command.execute.before`, which intercepts a command
+  someone else defined rather than defining one.
+- **`ai/model` in Pi.** `setModel` switches a model; `scopedModels` is a
+  read-only snapshot of what `--models` already scoped. Neither publishes a
+  registry.
+- **`ai/model` in OpenCode v2.** `catalog.model` requires `api`, `request`,
+  `time.released`, `limit.context`, `limit.output` and `status` — all required,
+  none published by a portable capability record. The v1 `config.provider`
+  models, whose fields are all optional, is the surface that maps.
+- **`agents` in both.** A Vibes `agents` descriptor is a deployment and roster
+  record. `config.agent` defines an OpenCode runner agent; a Vibes agent is not
+  an OpenCode agent definition, and projecting one would claim a roster controls
+  the host's agent set when it does not.
+- **`diagnostics/check`, `storage/*`.** These are internal machinery. A host has
+  no surface for them, and none is needed: an agent reaches storage through the
+  tools that use it, not by calling the adapter.
+
+A kind absent from this table is either not agent-facing, or a host has a surface
+for it that no current projection uses. Both are visible: `vibes runtime export`
+reports every kind the runtime holds.
+
+## Mapping rules that follow from these references
+
+1. **Map only what the host expresses.** OpenCode has no executable-command
+   plugin API, so a Vibes `cli/command` has no OpenCode mapping. Advertising one
+   would promise a capability the host cannot deliver.
+2. **Write only what the runtime knows.** OpenCode's v1 model fields are all
+   optional, so a model projects as its identity facts; a field the runtime does
+   not publish — a release date, a `limit` with only one of its two required
+   numbers — is omitted rather than guessed.
+3. **Never overwrite the host's own document.** A config projection merges per
+   key: a user's `npm`, `api`, `options` or `limit` survives, and only absent
+   keys are filled.
+4. **Report what you could not place.** A model naming no provider, or a provider
+   the registry does not declare, is logged with its reason. Inventing a provider
+   entry claims a provider exists; dropping the model silently reads as "the
+   runtime holds no such model".
+5. **The registry is the only catalog.** A host registers from a live query; no
+   host keeps a tool list, a command list, or a provider list of its own.
+6. **Names come from descriptors.** A host may project an id into a
+   host-legal name (Pi's underscore projection), but the descriptor stays the
+   routing identity and the source of the name.
+7. **Prompt text is never baked.** A prompt is built from what the host actually
+   registered, through the shared `buildHarnessSystemPrompt`, and a prompt
+   already carrying a provenance marker is left alone.
+8. **Approval is decided once.** The shared projection decides, from the
+   descriptor's own safety facts; a host supplies only the UI it asks through.
+9. **Boot through the kernel's one entry.** A host declares its environment and
+   composition and calls `bootstrapVibesRuntime` (directly, or via
+   `bootstrapNodeRuntime` / `VibesAgentHost.boot`). No host re-implements boot,
+   re-resolves config, or reaches around the registry.

package/dist/acp/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ACP (Agent Client Protocol) — runtime surface
+ *
+ * An IDE or another ACP client talks to a Vibes agent, and the tools and MCP
+ * servers behind that session resolve in `surface: 'agent'` scope.
+ *
+ * ACP is how outside hosts reach Vibes, so it lives in External beside the
+ * other projection mechanisms, the way `@vibesdotdev/mcp` owns the MCP
+ * surface. Third-party ACP server processes stay with PM.
+ *
+ * An ACP host declares its scope once, before boot, through the one entry
+ * (`bootstrapVibesRuntime`); nothing here boots, patches or re-activates a
+ * runtime. Every session runs on the runtime its host hands over.
+ */
+import type { RuntimeScope, VibesRuntime } from '@vibesdotdev/kernel';
+/**
+ * The surface and purpose an ACP host declares: an ACP session serves an
+ * agent. The host composes these into its declaration before boot; hardware,
+ * hosting and every other fact stay the host's own.
+ */
+export declare function acpRuntimeScope(): Pick<RuntimeScope, 'surface' | 'purpose'>;
+/**
+ * Run one ACP session's work on the runtime the host handed over, as an
+ * invocation whose actor carries the ACP session id (`harnessSessionId`).
+ * Session identity is per invocation, never a declared scope qualifier.
+ */
+export declare function runAcpSession<T>(runtime: VibesRuntime, sessionId: string, fn: () => T): T;
+//# sourceMappingURL=index.d.ts.map

package/dist/acp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/acp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,SAAS,CAAC,CAE3E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEzF"}

package/dist/acp/index.js

@@ -0,0 +1,31 @@
+/**
+ * ACP (Agent Client Protocol) — runtime surface
+ *
+ * An IDE or another ACP client talks to a Vibes agent, and the tools and MCP
+ * servers behind that session resolve in `surface: 'agent'` scope.
+ *
+ * ACP is how outside hosts reach Vibes, so it lives in External beside the
+ * other projection mechanisms, the way `@vibesdotdev/mcp` owns the MCP
+ * surface. Third-party ACP server processes stay with PM.
+ *
+ * An ACP host declares its scope once, before boot, through the one entry
+ * (`bootstrapVibesRuntime`); nothing here boots, patches or re-activates a
+ * runtime. Every session runs on the runtime its host hands over.
+ */
+/**
+ * The surface and purpose an ACP host declares: an ACP session serves an
+ * agent. The host composes these into its declaration before boot; hardware,
+ * hosting and every other fact stay the host's own.
+ */
+export function acpRuntimeScope() {
+    return { surface: 'agent', purpose: 'agent' };
+}
+/**
+ * Run one ACP session's work on the runtime the host handed over, as an
+ * invocation whose actor carries the ACP session id (`harnessSessionId`).
+ * Session identity is per invocation, never a declared scope qualifier.
+ */
+export function runAcpSession(runtime, sessionId, fn) {
+    return runtime.runInvocation(fn, { actor: { harness: 'acp', harnessSessionId: sessionId } });
+}
+//# sourceMappingURL=index.js.map

package/dist/acp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/acp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC9B,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAI,OAAqB,EAAE,SAAiB,EAAE,EAAW;IACrF,OAAO,OAAO,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;AAC9F,CAAC"}

package/dist/ambient/agent-roster-heartbeat.d.ts

@@ -0,0 +1,67 @@
+/** Resolve and publish the current runtime's agent-session identity. */
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+import type { AgentSessionAnnouncement } from '../schemas/agent-roster.ts';
+import { type AgentRosterProvider } from '../runtime/agent-roster-provider.ts';
+/**
+ * Build the portable heartbeat from runtime/session facts.
+ *
+ * Provider/model are never guessed from a brand name. A harness may report
+ * them via participant/client metadata or runtime env; configured Vibes agents
+ * can be enriched from the Agents + AI clients. Otherwise the wire carries
+ * explicit nulls and `vibes who` renders `unreported`.
+ */
+export declare function resolveCurrentAgentSessionAnnouncement(runtime: RuntimeRef, now?: Date): Promise<AgentSessionAnnouncement | null>;
+export declare function resolveAgentRosterProvider(runtime: RuntimeRef, providerId?: string): Promise<AgentRosterProvider | null>;
+export declare function announceCurrentAgentSession(runtime: RuntimeRef, now?: Date): Promise<AgentSessionAnnouncement | null>;
+/**
+ * Longest gap the runtime leaves between roster writes while the session is
+ * unchanged.
+ *
+ * The server holds an announcement for its own TTL (15 minutes, see hq-web's
+ * `AGENT_ROSTER_TTL_SECONDS`) and expires crashed sessions on read, so staying
+ * listed only requires a write comfortably inside that window — not one per
+ * tick. This keepalive leaves a 10x margin under the TTL while still sitting
+ * under the 3-minute freshness convention used elsewhere for hosts.
+ */
+export declare const AGENT_ROSTER_KEEPALIVE_MS: number;
+/**
+ * Everything the roster row carries except the observation timestamp.
+ *
+ * `observedAt` advances on every tick by construction, so comparing whole
+ * entries would report "changed" forever. Two entries with the same fingerprint
+ * describe the same session doing the same work, and the later one tells the
+ * server nothing it does not already hold.
+ */
+export declare function agentSessionAnnouncementFingerprint(entry: AgentSessionAnnouncement): string;
+/** Mutable coalescing state; one per runtime, owned by the caller's timer. */
+export interface AgentRosterAnnounceState {
+    fingerprint?: string;
+    announcedAt?: number;
+    /**
+     * Set when the provider refused the credential this runtime presented: a
+     * SHA-256 digest of that credential (never the credential). While the
+     * runtime still presents it, no beat publishes; a changed credential
+     * clears it.
+     */
+    refusedCredential?: string;
+}
+/**
+ * Announce the current session only when it actually changed, or when the
+ * keepalive falls due.
+ *
+ * Resolution stays local (session manager + model enrichment); only the write
+ * crosses the network, so an idle body costs nothing but the resolve it was
+ * already doing. Returns the entry when it published, `null` when it had
+ * nothing new to say — callers that must publish unconditionally should use
+ * `announceCurrentAgentSession`.
+ *
+ * `signal` is the caller's run: once it aborts (its runtime's disposal began)
+ * the announce publishes nothing and rejects with the signal's reason, and a
+ * publish in flight is aborted.
+ *
+ * A provider refusal (`agent-roster-unauthorized`) rejects once; later calls
+ * return `null` without publishing until the runtime presents a different
+ * credential.
+ */
+export declare function announceCurrentAgentSessionIfDue(runtime: RuntimeRef, state: AgentRosterAnnounceState, now?: Date, signal?: AbortSignal): Promise<AgentSessionAnnouncement | null>;
+//# sourceMappingURL=agent-roster-heartbeat.d.ts.map

package/dist/ambient/agent-roster-heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-roster-heartbeat.d.ts","sourceRoot":"","sources":["../../src/ambient/agent-roster-heartbeat.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAGxE,OAAO,EAKN,KAAK,UAAU,EACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAC3E,OAAO,EAKN,KAAK,mBAAmB,EACxB,MAAM,qCAAqC,CAAC;AA8G7C;;;;;;;GAOG;AACH,wBAAsB,sCAAsC,CAC3D,OAAO,EAAE,UAAU,EACnB,GAAG,OAAa,GACd,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC,CA4E1C;AAED,wBAAsB,0BAA0B,CAC/C,OAAO,EAAE,UAAU,EACnB,UAAU,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAkBrC;AAED,wBAAsB,2BAA2B,CAChD,OAAO,EAAE,UAAU,EACnB,GAAG,OAAa,GACd,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC,CAM1C;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,QAAY,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,CAO3F;AAED,8EAA8E;AAC9E,MAAM,WAAW,wBAAwB;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAyBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gCAAgC,CACrD,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,wBAAwB,EAC/B,GAAG,OAAa,EAChB,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC,CA0B1C"}