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

package/dist/projection/attestation.js

@@ -0,0 +1,59 @@
+/**
+ * Host-side contract for the MCP projection doctor.
+ *
+ * External adapters are the only honest observers of a host's post-handshake
+ * tool index. The nonce prevents replaying an old catalog report as proof for a
+ * new server birth. This helper validates the boundary; it does not pretend to
+ * provide a cryptographic signature for an untrusted host process.
+ */
+/** Must match the MCP server's catalog equality fingerprint. */
+export function projectionCatalogHash(toolIds) {
+    const canonical = JSON.stringify([...new Set(toolIds)].sort());
+    let hash = 0xcbf29ce484222325n;
+    for (const byte of new TextEncoder().encode(canonical)) {
+        hash ^= BigInt(byte);
+        hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+    }
+    return hash.toString(16).padStart(16, '0');
+}
+export function createProjectionDoctorChallenge(input) {
+    const now = input.now ?? new Date();
+    const ttlMs = input.ttlMs ?? 5 * 60_000;
+    return {
+        version: 1,
+        nonce: crypto.randomUUID(),
+        clientId: input.clientId,
+        issuedAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+        birthCatalogHash: input.birthCatalogHash
+    };
+}
+export function verifyProjectionHostAttestation(challenge, attestation, now = new Date()) {
+    if (attestation.nonce !== challenge.nonce)
+        return { ok: false, failure: 'nonce-mismatch' };
+    if (attestation.clientId !== challenge.clientId)
+        return { ok: false, failure: 'client-mismatch' };
+    const expiresAt = Date.parse(challenge.expiresAt);
+    if (!Number.isFinite(expiresAt) || now.getTime() > expiresAt) {
+        return { ok: false, failure: 'expired' };
+    }
+    if (attestation.birthCatalogHash !== challenge.birthCatalogHash) {
+        return { ok: false, failure: 'birth-hash-mismatch' };
+    }
+    if (attestation.visibleToolIds.length === 0)
+        return { ok: false, failure: 'empty-catalog' };
+    if (!attestation.visibleCatalogHash ||
+        attestation.visibleCatalogHash !== projectionCatalogHash(attestation.visibleToolIds)) {
+        return { ok: false, failure: 'catalog-hash-mismatch' };
+    }
+    if (challenge.birthCatalogHash && attestation.visibleCatalogHash !== challenge.birthCatalogHash) {
+        return { ok: false, failure: 'visible-catalog-mismatch' };
+    }
+    if (!attestation.visibleToolIds.includes(attestation.canary.toolId)) {
+        return { ok: false, failure: 'canary-not-visible' };
+    }
+    if (attestation.canary.status !== 'passed')
+        return { ok: false, failure: 'canary-failed' };
+    return { ok: true };
+}
+//# sourceMappingURL=attestation.js.map

package/dist/projection/attestation.js.map

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

package/dist/runtime/agent-roster-provider.d.ts

@@ -0,0 +1,75 @@
+/** Runtime provider seam for the account-wide live agent roster. */
+import type { AgentSessionAnnouncement } from '../schemas/agent-roster.ts';
+export declare const EXTERNAL_AGENT_ROSTER_PROVIDER_KIND: "external/agent-roster-provider";
+export declare const ACCOUNT_AGENT_ROSTER_PROVIDER_ID: "external.agent-roster.account";
+export declare const AGENT_ROSTER_PROVIDER_QUALIFIER: "agentRosterProviderId";
+/** A run's options for {@link AgentRosterProvider.announce}. */
+export interface AgentRosterAnnounceOptions {
+    /** The caller's run; once it aborts the provider publishes nothing and settles. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Why a roster publish was refused: the provider rejected the credential it
+ * presented (`AUTH_REQUIRED` or `PERMISSION_DENIED`, not retryable). The same
+ * credential will be refused again, so a heartbeat stops until it changes.
+ */
+export declare const AGENT_ROSTER_UNAUTHORIZED_REASON: "agent-roster-unauthorized";
+export interface AgentRosterProvider {
+    announce(entry: AgentSessionAnnouncement, options?: AgentRosterAnnounceOptions): Promise<void>;
+    list(): Promise<AgentSessionAnnouncement[]>;
+}
+export declare const externalAgentRosterProviderKind: import("@vibesdotdev/kernel").RuntimeKindDescriptorRecord<unknown>;
+export interface AgentRosterProviderDescriptorInput {
+    id: string;
+    name: string;
+    description: string;
+    hardware?: readonly string[];
+}
+/** Build a selectable provider descriptor for first-party or whitelabel hosts. */
+export declare function createAgentRosterProviderDescriptor(input: AgentRosterProviderDescriptorInput): {
+    id: string;
+    kind: string;
+    name?: string | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    hardware?: string[] | undefined;
+    enabled?: boolean | undefined;
+    priority?: number | undefined;
+    capabilityId?: string | undefined;
+    requiredContext?: string[] | undefined;
+    optionalContext?: string[] | undefined;
+    config?: unknown;
+    retention?: string | {
+        reason: string;
+        maxAgeDays?: number | undefined;
+        maxEntries?: number | undefined;
+        maxBytes?: number | undefined;
+        cascadeFrom?: string | undefined;
+        ageField?: string | undefined;
+        enforcedBy?: string | undefined;
+    } | undefined;
+};
+export declare const accountAgentRosterProviderDescriptor: {
+    id: string;
+    kind: string;
+    name?: string | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    hardware?: string[] | undefined;
+    enabled?: boolean | undefined;
+    priority?: number | undefined;
+    capabilityId?: string | undefined;
+    requiredContext?: string[] | undefined;
+    optionalContext?: string[] | undefined;
+    config?: unknown;
+    retention?: string | {
+        reason: string;
+        maxAgeDays?: number | undefined;
+        maxEntries?: number | undefined;
+        maxBytes?: number | undefined;
+        cascadeFrom?: string | undefined;
+        ageField?: string | undefined;
+        enforcedBy?: string | undefined;
+    } | undefined;
+};
+//# sourceMappingURL=agent-roster-provider.d.ts.map

package/dist/runtime/agent-roster-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-roster-provider.d.ts","sourceRoot":"","sources":["../../src/runtime/agent-roster-provider.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAIpE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAE3E,eAAO,MAAM,mCAAmC,EAAG,gCAAyC,CAAC;AAC7F,eAAO,MAAM,gCAAgC,EAAG,+BAAwC,CAAC;AACzF,eAAO,MAAM,+BAA+B,EAAG,uBAAgC,CAAC;AAEhF,gEAAgE;AAChE,MAAM,WAAW,0BAA0B;IAC1C,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,EAAG,2BAAoC,CAAC;AAErF,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,KAAK,EAAE,wBAAwB,EAAE,OAAO,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/F,IAAI,IAAI,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAAC;CAC5C;AAED,eAAO,MAAM,+BAA+B,oEAG1C,CAAC;AAEH,MAAM,WAAW,kCAAkC;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,kFAAkF;AAClF,wBAAgB,mCAAmC,CAClD,KAAK,EAAE,kCAAkC;;;;;;;;;;;;;;;;;;;;;;EAOzC;AAED,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;;CAK/C,CAAC"}

package/dist/runtime/agent-roster-provider.js

@@ -0,0 +1,30 @@
+/** Runtime provider seam for the account-wide live agent roster. */
+import { createRuntimeKind } from '@vibesdotdev/kernel';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/kernel/schemas/descriptor';
+export const EXTERNAL_AGENT_ROSTER_PROVIDER_KIND = 'external/agent-roster-provider';
+export const ACCOUNT_AGENT_ROSTER_PROVIDER_ID = 'external.agent-roster.account';
+export const AGENT_ROSTER_PROVIDER_QUALIFIER = 'agentRosterProviderId';
+/**
+ * Why a roster publish was refused: the provider rejected the credential it
+ * presented (`AUTH_REQUIRED` or `PERMISSION_DENIED`, not retryable). The same
+ * credential will be refused again, so a heartbeat stops until it changes.
+ */
+export const AGENT_ROSTER_UNAUTHORIZED_REASON = 'agent-roster-unauthorized';
+export const externalAgentRosterProviderKind = createRuntimeKind({
+    id: EXTERNAL_AGENT_ROSTER_PROVIDER_KIND,
+    descriptorSchema: RuntimeDescriptorSchema
+});
+/** Build a selectable provider descriptor for first-party or whitelabel hosts. */
+export function createAgentRosterProviderDescriptor(input) {
+    return RuntimeDescriptorSchema.parse({
+        ...input,
+        kind: EXTERNAL_AGENT_ROSTER_PROVIDER_KIND,
+        hardware: input.hardware ?? ['consumer']
+    });
+}
+export const accountAgentRosterProviderDescriptor = createAgentRosterProviderDescriptor({
+    id: ACCOUNT_AGENT_ROSTER_PROVIDER_ID,
+    name: 'Account agent roster provider',
+    description: 'Publishes and lists live agent sessions across every environment linked to the account'
+});
+//# sourceMappingURL=agent-roster-provider.js.map

package/dist/runtime/agent-roster-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-roster-provider.js","sourceRoot":"","sources":["../../src/runtime/agent-roster-provider.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAEpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AAGjF,MAAM,CAAC,MAAM,mCAAmC,GAAG,gCAAyC,CAAC;AAC7F,MAAM,CAAC,MAAM,gCAAgC,GAAG,+BAAwC,CAAC;AACzF,MAAM,CAAC,MAAM,+BAA+B,GAAG,uBAAgC,CAAC;AAQhF;;;;GAIG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,2BAAoC,CAAC;AAOrF,MAAM,CAAC,MAAM,+BAA+B,GAAG,iBAAiB,CAAC;IAChE,EAAE,EAAE,mCAAmC;IACvC,gBAAgB,EAAE,uBAAuB;CACzC,CAAC,CAAC;AASH,kFAAkF;AAClF,MAAM,UAAU,mCAAmC,CAClD,KAAyC;IAEzC,OAAO,uBAAuB,CAAC,KAAK,CAAC;QACpC,GAAG,KAAK;QACR,IAAI,EAAE,mCAAmC;QACzC,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,CAAC,UAAU,CAAC;KACxC,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,oCAAoC,GAAG,mCAAmC,CAAC;IACvF,EAAE,EAAE,gCAAgC;IACpC,IAAI,EAAE,+BAA+B;IACrC,WAAW,EACV,wFAAwF;CACzF,CAAC,CAAC"}

package/dist/runtime/external-surface-projector.d.ts

@@ -0,0 +1,37 @@
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+import * as z from 'zod/v4';
+import type { ExternalHostDescriptor } from '../external-tool/schemas/tool.ts';
+import type { ExternalOperationDescriptor } from '../runtime.ts';
+export declare const EXTERNAL_CLI_PROJECTOR_KIND: "external/cli-projector";
+export declare const EXTERNAL_CLI_PROJECTOR_ID: "external";
+export declare const ExternalCLIProjectorDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hardware: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    capabilityId: z.ZodOptional<z.ZodString>;
+    requiredContext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    optionalContext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    config: z.ZodOptional<z.ZodUnknown>;
+    retention: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        maxAgeDays: z.ZodOptional<z.ZodNumber>;
+        maxEntries: z.ZodOptional<z.ZodNumber>;
+        maxBytes: z.ZodOptional<z.ZodNumber>;
+        cascadeFrom: z.ZodOptional<z.ZodString>;
+        ageField: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+        enforcedBy: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+    kind: z.ZodLiteral<"external/cli-projector">;
+}, z.core.$strip>;
+export interface ExternalCLIProjector {
+    projectHost(descriptor: ExternalHostDescriptor): void;
+    projectOperation(descriptor: ExternalOperationDescriptor): void;
+    projectAll(): void;
+}
+export declare const externalCliProjectorKind: import("@vibesdotdev/kernel").RuntimeKindDescriptorRecord<unknown>;
+export declare function resolveExternalCLIProjector(runtime: RuntimeRef): Promise<ExternalCLIProjector | undefined>;
+//# sourceMappingURL=external-surface-projector.d.ts.map

package/dist/runtime/external-surface-projector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-surface-projector.d.ts","sourceRoot":"","sources":["../../src/runtime/external-surface-projector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEzE,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC/E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAEjE,eAAO,MAAM,2BAA2B,EAAG,wBAAiC,CAAC;AAC7E,eAAO,MAAM,yBAAyB,EAAG,UAAmB,CAAC;AAE7D,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;;iBAE/C,CAAC;AAEH,MAAM,WAAW,oBAAoB;IACpC,WAAW,CAAC,UAAU,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtD,gBAAgB,CAAC,UAAU,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAChE,UAAU,IAAI,IAAI,CAAC;CACnB;AAED,eAAO,MAAM,wBAAwB,oEAGnC,CAAC;AAEH,wBAAsB,2BAA2B,CAChD,OAAO,EAAE,UAAU,GACjB,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAK3C"}

package/dist/runtime/external-surface-projector.js

@@ -0,0 +1,21 @@
+import { createRuntimeKind } from '@vibesdotdev/kernel';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/kernel/schemas/descriptor';
+import * as z from 'zod/v4';
+export const EXTERNAL_CLI_PROJECTOR_KIND = 'external/cli-projector';
+export const EXTERNAL_CLI_PROJECTOR_ID = 'external';
+export const ExternalCLIProjectorDescriptorSchema = RuntimeDescriptorSchema.extend({
+    kind: z.literal(EXTERNAL_CLI_PROJECTOR_KIND)
+});
+export const externalCliProjectorKind = createRuntimeKind({
+    id: EXTERNAL_CLI_PROJECTOR_KIND,
+    descriptorSchema: ExternalCLIProjectorDescriptorSchema
+});
+export async function resolveExternalCLIProjector(runtime) {
+    if (!runtime.hasKind(EXTERNAL_CLI_PROJECTOR_KIND))
+        return undefined;
+    const query = runtime.query(EXTERNAL_CLI_PROJECTOR_KIND).withId(EXTERNAL_CLI_PROJECTOR_ID);
+    if (query.descriptors().length === 0)
+        return undefined;
+    return query.resolve();
+}
+//# sourceMappingURL=external-surface-projector.js.map

package/dist/runtime/external-surface-projector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-surface-projector.js","sourceRoot":"","sources":["../../src/runtime/external-surface-projector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAmB,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACjF,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAI5B,MAAM,CAAC,MAAM,2BAA2B,GAAG,wBAAiC,CAAC;AAC7E,MAAM,CAAC,MAAM,yBAAyB,GAAG,UAAmB,CAAC;AAE7D,MAAM,CAAC,MAAM,oCAAoC,GAAG,uBAAuB,CAAC,MAAM,CAAC;IAClF,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,2BAA2B,CAAC;CAC5C,CAAC,CAAC;AAQH,MAAM,CAAC,MAAM,wBAAwB,GAAG,iBAAiB,CAAC;IACzD,EAAE,EAAE,2BAA2B;IAC/B,gBAAgB,EAAE,oCAAoC;CACtD,CAAC,CAAC;AAEH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAChD,OAAmB;IAEnB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,2BAA2B,CAAC;QAAE,OAAO,SAAS,CAAC;IACpE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAA8E,2BAA2B,CAAC,CAAC,MAAM,CAAC,yBAAyB,CAAC,CAAC;IACxK,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACvD,OAAO,KAAK,CAAC,OAAO,EAAE,CAAC;AACxB,CAAC"}

package/dist/runtime/lifecycle-task.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Background work the external plugin starts, owned by the runtime it runs on
+ * (RC07).
+ *
+ * The plugin starts work from its activation and its lifecycle intervals (the
+ * agent roster heartbeat, file-access retention). That work must not outlive
+ * its runtime, so each run is a `runtime.lifecycle.wait`:
+ *
+ * - a runtime whose disposal began (`lifecycle.phase` is not `live`) starts no run;
+ * - disposal aborts the run's signal, and its wait ends `CANCELLED`
+ *   `wait-aborted`: a confirmed cancellation, not a failure;
+ * - `dispose()` joins work still running within the finalization budget. A
+ *   cancellation that work meets once its signal aborted (Storage and LocalDB
+ *   refuse new work on a runtime whose disposal began) is the wait's own, and
+ *   is joined without a second report;
+ * - any other failure is reported once on the runtime's kernel diagnostics
+ *   port, never printed and dropped. A failure the run meets after its signal
+ *   aborted is reported under the task's own name and then ends the run as
+ *   that wait's cancellation, so the runtime never counts it as a late
+ *   failure of its own, and it never fails `dispose()`.
+ *
+ * Runtime keeps its owned-work primitive private (`ownDerivedWork`); this
+ * module uses the public `wait` until Runtime publishes one.
+ */
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+/** Where a failed run is reported: one bounded, redacted diagnostics line. */
+export interface LifecycleTaskReport {
+    readonly scope: string;
+    readonly plugin: string;
+    readonly action: string;
+}
+/** One run of lifecycle-owned work. */
+export interface LifecycleTask {
+    /** What the run waits for, named in its wait. */
+    readonly reason: string;
+    /** Upper bound for one run; a run past it is reported as a failure. */
+    readonly timeoutMs: number;
+    readonly report: LifecycleTaskReport;
+    /** The work; its signal aborts when the runtime's disposal begins. */
+    readonly work: (signal: AbortSignal) => Promise<void>;
+}
+/**
+ * Run `task` once as work `runtime` owns. Resolves when the run ends; never
+ * rejects. A cancelled run ends quietly, and any other failure is reported on
+ * the runtime's kernel diagnostics port.
+ */
+/** The outcome a caller can count: settled, or failed and reported. */
+export declare function startLifecycleTask(runtime: RuntimeRef, task: LifecycleTask): {
+    completion: Promise<"cancelled" | "failed" | "settled">;
+    settlement: Promise<void>;
+};
+/** Compatibility entrypoint: bounded outcome; the kernel still tracks unsettled work. */
+export declare function runLifecycleTask(runtime: RuntimeRef, task: LifecycleTask): Promise<'settled' | 'failed' | 'cancelled'>;
+//# sourceMappingURL=lifecycle-task.d.ts.map

package/dist/runtime/lifecycle-task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-task.d.ts","sourceRoot":"","sources":["../../src/runtime/lifecycle-task.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAKN,KAAK,UAAU,EACf,MAAM,qBAAqB,CAAC;AAE7B,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AAuDD;;;;GAIG;AACH,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa;;;EA0B1E;AAED,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC,CAEtH"}

package/dist/runtime/lifecycle-task.js

@@ -0,0 +1,111 @@
+/**
+ * Background work the external plugin starts, owned by the runtime it runs on
+ * (RC07).
+ *
+ * The plugin starts work from its activation and its lifecycle intervals (the
+ * agent roster heartbeat, file-access retention). That work must not outlive
+ * its runtime, so each run is a `runtime.lifecycle.wait`:
+ *
+ * - a runtime whose disposal began (`lifecycle.phase` is not `live`) starts no run;
+ * - disposal aborts the run's signal, and its wait ends `CANCELLED`
+ *   `wait-aborted`: a confirmed cancellation, not a failure;
+ * - `dispose()` joins work still running within the finalization budget. A
+ *   cancellation that work meets once its signal aborted (Storage and LocalDB
+ *   refuse new work on a runtime whose disposal began) is the wait's own, and
+ *   is joined without a second report;
+ * - any other failure is reported once on the runtime's kernel diagnostics
+ *   port, never printed and dropped. A failure the run meets after its signal
+ *   aborted is reported under the task's own name and then ends the run as
+ *   that wait's cancellation, so the runtime never counts it as a late
+ *   failure of its own, and it never fails `dispose()`.
+ *
+ * Runtime keeps its owned-work primitive private (`ownDerivedWork`); this
+ * module uses the public `wait` until Runtime publishes one.
+ */
+import { CaughtFailureSchema, isCapabilityError } from '@vibesdotdev/kernel';
+function settle(operation) {
+    return operation.then(() => ({ failed: false }), (cause) => ({ failed: true, cause }));
+}
+/**
+ * A cancellation: the established outcome of work its runtime or caller ended.
+ * That is a `CANCELLED` refusal, or the kernel lifecycle's own refusal to start
+ * work on a runtime that was disposed (`runtime-disposed`): a short CLI run ends
+ * while its heartbeat is mid-flight, and that is the run ending, not a failure.
+ */
+function isCancellation(failure) {
+    return isCapabilityError(failure) && (failure.code === 'CANCELLED' || failure.reason === 'runtime-disposed');
+}
+/** Report a run's failure: one bounded, redacted line on the runtime's kernel diagnostics port. */
+function report(runtime, task, failure) {
+    const diagnostics = runtime.diagnostics;
+    diagnostics.error(task.report.action, {
+        scope: task.report.scope,
+        plugin: task.report.plugin,
+        error: failure
+    });
+}
+/**
+ * The work as its wait runs it. Once the run's signal aborted, the wait has
+ * already ended: a cancellation the work then meets is that wait's own, and
+ * any other failure is reported here, under the task's name, before the run
+ * ends as the same cancellation. `dispose()` joins either without a second
+ * report.
+ */
+function cancellable(runtime, task) {
+    return async (signal) => {
+        try {
+            await task.work(signal);
+        }
+        catch (error) {
+            if (!signal.aborted)
+                throw error;
+            const failure = CaughtFailureSchema.parse(error);
+            if (!isCancellation(failure))
+                report(runtime, task, failure);
+            signal.throwIfAborted();
+            throw error;
+        }
+    };
+}
+/**
+ * Run `task` once as work `runtime` owns. Resolves when the run ends; never
+ * rejects. A cancelled run ends quietly, and any other failure is reported on
+ * the runtime's kernel diagnostics port.
+ */
+/** The outcome a caller can count: settled, or failed and reported. */
+export function startLifecycleTask(runtime, task) {
+    if (runtime.lifecycle.phase !== 'live') {
+        return { completion: Promise.resolve('cancelled'), settlement: Promise.resolve() };
+    }
+    let started = false;
+    let settled;
+    const settlement = new Promise((resolve) => { settled = resolve; });
+    const work = cancellable(runtime, task);
+    const completion = (async () => {
+        const run = await settle(runtime.lifecycle.wait(async (signal) => {
+            started = true;
+            try {
+                await work(signal);
+            }
+            finally {
+                settled();
+            }
+        }, { timeoutMs: task.timeoutMs, reason: task.reason }));
+        // Admission can fail before the kernel invokes work.
+        if (!started)
+            settled();
+        if (!run.failed)
+            return 'settled';
+        const failure = CaughtFailureSchema.parse(run.cause);
+        if (isCancellation(failure))
+            return 'cancelled';
+        report(runtime, task, failure);
+        return 'failed';
+    })();
+    return { completion, settlement };
+}
+/** Compatibility entrypoint: bounded outcome; the kernel still tracks unsettled work. */
+export function runLifecycleTask(runtime, task) {
+    return startLifecycleTask(runtime, task).completion;
+}
+//# sourceMappingURL=lifecycle-task.js.map

package/dist/runtime/lifecycle-task.js.map

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