@kybernesis/kyberagent-extension-sdk 0.1.0-alpha

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { d as AgentId, A as AnsweringPort, e as BlockedReason, b as BrainHit, B as BrainReadPort, a as BrainStatsView, f as BridgeDeclaration, C as ComposerCapabilityPort, g as ComposerDescriptor, h as ContributionKeyInput, D as DataEndpointPort, i as EXTENSION_HOST_SLOTS, j as EventSourcePort, k as ExtensionBridgeContributionDefinition, l as ExtensionComposerCapabilityDefinition, m as ExtensionContextualActionDefinition, n as ExtensionContributionDefinition, o as ExtensionDataEndpointDefinition, E as ExtensionDefinition, p as ExtensionHostSlot, q as ExtensionRuntime, r as ExtensionSettingsPanelDefinition, s as ExtensionSidecarContributionDefinition, t as ExtensionSurfaceDefinition, u as ExtensionWorkspaceTabDefinition, G as GatedHostPortFactory, v as HostCapabilityId, w as HostCommandDescriptor, x as HostCommandPort, y as HostContextPort, z as HostContextSnapshot, F as HostEventPort, H as HostPort, I as InvokablePort, K as KernelPermissionId, J as KernelPluginRegistryEntry, L as KernelRegistrySnapshot, N as NormalizedPluginExtensionContributionSet, M as PluginManifestContribution, O as PluginShipsState, Q as PluginThemeTokenSet, P as PortInjectionResult, R as ProviderRuntimeProjectionDescriptor, S as SeamCallContext, T as SeamPermissionDenied, U as SidecarDeclaration, V as VerifiedPrincipal, W as WorkspaceTabContributionMetadata, X as canonicalHostCapabilities, Y as defineBridge, Z as defineBridgeContribution, _ as defineComposerCapability, $ as defineContextualAction, a0 as defineDataEndpoint, a1 as defineExtension, a2 as defineProviderRuntimeProjection, a3 as defineSettingsPanel, a4 as defineSidecar, a5 as defineSidecarContribution, a6 as defineSurface, a7 as defineThemeTokens, a8 as deriveExtensionHostCapabilities, a9 as emitExtensionContributionSet, aa as gatedHostPort, ab as hostSlots, ac as makeAgentId, ad as makeSeamCallContext, ae as requiresHostCapabilities, af as requiresKernelPermissions, ag as validateDefinitionCrossRefs, ah as validateExtensionDefinition, ai as workspaceTab } from './index-M4tx9uKW.js';
+import 'effect';

package/dist/index.js

@@ -0,0 +1,57 @@
+import {
+  EXTENSION_HOST_SLOTS,
+  SeamPermissionDenied,
+  canonicalHostCapabilities,
+  defineBridge,
+  defineBridgeContribution,
+  defineComposerCapability,
+  defineContextualAction,
+  defineDataEndpoint,
+  defineExtension,
+  defineProviderRuntimeProjection,
+  defineSettingsPanel,
+  defineSidecar,
+  defineSidecarContribution,
+  defineSurface,
+  defineThemeTokens,
+  deriveExtensionHostCapabilities,
+  emitExtensionContributionSet,
+  gatedHostPort,
+  hostSlots,
+  makeAgentId,
+  makeSeamCallContext,
+  requiresHostCapabilities,
+  requiresKernelPermissions,
+  validateDefinitionCrossRefs,
+  validateExtensionDefinition,
+  workspaceTab
+} from "./chunk-ZDAZ7Q2A.js";
+export {
+  EXTENSION_HOST_SLOTS,
+  SeamPermissionDenied,
+  canonicalHostCapabilities,
+  defineBridge,
+  defineBridgeContribution,
+  defineComposerCapability,
+  defineContextualAction,
+  defineDataEndpoint,
+  defineExtension,
+  defineProviderRuntimeProjection,
+  defineSettingsPanel,
+  defineSidecar,
+  defineSidecarContribution,
+  defineSurface,
+  defineThemeTokens,
+  deriveExtensionHostCapabilities,
+  emitExtensionContributionSet,
+  gatedHostPort,
+  hostSlots,
+  makeAgentId,
+  makeSeamCallContext,
+  requiresHostCapabilities,
+  requiresKernelPermissions,
+  validateDefinitionCrossRefs,
+  validateExtensionDefinition,
+  workspaceTab
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/testing/index.d.ts

@@ -0,0 +1,234 @@
+import { B as BrainReadPort, a as BrainStatsView, b as BrainHit, S as SeamCallContext, K as KernelPermissionId, H as HostPort, V as VerifiedPrincipal, E as ExtensionDefinition, A as AnsweringPort, P as PortInjectionResult, c as SeamResponse, d as AgentId } from '../index-M4tx9uKW.js';
+import 'effect';
+
+/**
+ * The behavioural host port an extension is INJECTED with — the testing seam.
+ *
+ * This is the "safe half" of the seam's dependency-injection story (SPEC Track 2):
+ * an extension contribution should *receive* its host collaborators rather than
+ * reach for a daemon global, so it can be unit-tested against a fake. The injector
+ * is the runner — the host in production, the test harness in tests.
+ *
+ * DELIBERATELY MINIMAL, on two axes:
+ *  - Surface: only the brain READ channel is modelled — the one a data extension
+ *    actually uses today. The full channel taxonomy is still under review
+ *    (capability-model.md), so this is NOT a cemented contract.
+ *  - Capability: an extension gets a NARROW read port (`BrainReadPort`), not the
+ *    full write-capable `@kybernesis/brain-contracts` `BrainProvider`. Extensions
+ *    only *consume* the host-owned brain (capability-model rule 3), so interface
+ *    segregation applies. Aligning these signatures with the real provider so the
+ *    production host can satisfy this port directly is the production-DI step
+ *    (host PR) — see docs/kdd/decisions/adr-0028-autonomous-execution-stops-at-the-host-runtime-boundary-host.md.
+ */
+
+/**
+ * The NARROW seed host port (brain.read only). Superseded by `HostPort` in
+ * ../seam-ports.ts; kept until Phase 5 retires it. `InMemoryHost` implements both.
+ */
+interface ExtensionHostPort {
+    brain(agentName: string): BrainReadPort;
+}
+
+type InMemoryAgentBrain = {
+    entities?: {
+        id: string;
+        title: string;
+    }[];
+    notes?: string[];
+};
+/**
+ * A real-but-lightweight brain read provider backed by an in-memory seed — the
+ * "Fake" category (xUnit), named by backing strategy to sit beside the real
+ * Remote/local `BrainProvider`. Deterministic and daemon-free: a unit test can
+ * exercise a brain-reading extension without SQLite, Cortex, or a running daemon.
+ */
+declare class InMemoryBrainProvider implements BrainReadPort {
+    private readonly seed;
+    constructor(seed?: InMemoryAgentBrain);
+    stats(): Promise<BrainStatsView>;
+    query(text: string, opts?: {
+        limit?: number;
+    }): Promise<BrainHit[]>;
+}
+/**
+ * In-memory implementation of the host port: the test harness plays the host's
+ * injector role and hands each agent its own InMemoryBrainProvider (brain is
+ * agent-keyed). Seed per agent; an unseeded agent gets an empty brain.
+ */
+declare class InMemoryHost implements ExtensionHostPort {
+    private readonly brains;
+    constructor(seed?: Record<string, InMemoryAgentBrain>);
+    brain(agentName: string): InMemoryBrainProvider;
+    /**
+     * Inject a gated, ctx-bound `HostPort` — the GROWN contract an extension actually
+     * consumes (red-team A1/A3; P5-PORTS-1 brought forward as conformance-prep). The
+     * runner builds the raw port from this host's in-memory state, binds the active
+     * agent from `ctx`, then wraps it in `gatedHostPort(grants)` — the SAME gate
+     * production uses (SDK-N3). This is what makes C9 ("green against InMemoryHost")
+     * a real conformance check instead of a vacuous one.
+     */
+    inject(ctx: SeamCallContext, grants: ReadonlySet<KernelPermissionId>): HostPort;
+}
+
+/**
+ * The C1–C16 conformance suite — the Extension SDK spec, MECHANICALLY ENFORCED.
+ *
+ * This module is the Phase-4 deliverable of the SDK-coherence program (docs/61).
+ * docs/65 §5 states the conformance requirements in prose; THIS file encodes them as
+ * runnable checks an extension is run through against `InMemoryHost` (the DI test
+ * host, ADR-3). The suite IS the spec: a requirement that isn't a check here isn't
+ * enforced, and a check that no reference extension exercises is vacuous — so the
+ * suite carries BOTH ≥2 distinct conformant reference extensions (must pass) AND a
+ * negative fixture per check (must be REJECTED). The Phase-3 red-team killed the old
+ * harness for being green over only-good inputs; the negatives are the fix.
+ *
+ * FREEZE (ADR-6): this is conformance-prep, freeze-EXEMPT, and lives entirely under
+ * `packages/extension-sdk/src/testing/`. It touches no production runtime (daemon,
+ * desktop). It DEFINES what Phase-5 production code must satisfy; it does not write it.
+ *
+ * RED BY DESIGN (docs/61 `phase4_will_be_red_until_phase5`): C10/C11/C12, C14/C15,
+ * the grant-store and the agent-registry mint are HOST/BUILDER-side and have no
+ * production impl yet. They are modelled as `phase5` checks behind DI seams
+ * (`ConformanceWiring`): with the seam absent (today) they report a RED "pending"
+ * row but do NOT fail the process — so the suite stays green for the other devs while
+ * being honestly red-in-meaning. When Phase 5 wires a seam in (from a daemon-side
+ * test importing this suite), the check runs for real and a regression fails loudly.
+ * `CONFORMANCE_STRICT=1` makes pending rows fail the process too (CI gate once ready).
+ */
+
+/**
+ * One extension, as the conformance suite needs to see it: its DECLARED shape (the
+ * definition — permissions, contributions) AND its RUNTIME behaviour (answering ports
+ * wired to an injected host). A conformant extension passes every `enforced` check;
+ * a negative fixture is tagged with the one check it is built to violate.
+ */
+interface ConformanceSubject {
+    readonly name: string;
+    /** Host-attested principal — what the host would stamp (never read from a payload). */
+    readonly principal: VerifiedPrincipal;
+    /** The declared definition (built via the define* builders). */
+    readonly definition: ExtensionDefinition;
+    /**
+     * Wire the answering EXT ports to an INJECTED (already-gated) host port, keyed by
+     * contributionId. This is the runtime moment: the host injects the port at
+     * activation and the contributions close over it. Rendering kinds (surface,
+     * settingsPanel) contribute NO answering port (C8).
+     */
+    activate(host: HostPort): ReadonlyMap<string, AnsweringPort>;
+    /**
+     * The identity the extension would act under, given its call context and a
+     * (possibly forged) extensionId arriving in a payload. Conformant ⇒ `ctx.principal.id`,
+     * NEVER the payload value (C4). A harness probe because "where did identity come
+     * from" is otherwise invisible from the outside.
+     */
+    identityProbe(ctx: SeamCallContext, forgedExtensionId: string): string;
+}
+/** A negative fixture: a subject built to FAIL exactly one check, proving it bites. */
+interface NegativeFixture {
+    readonly violates: string;
+    readonly subject: ConformanceSubject;
+}
+type SeamRouteOp = 'query' | 'describe' | 'invoke' | 'subscribe' | 'drain';
+/**
+ * The Phase-5 PRODUCTION seam runner contract (the daemon host-side path). The suite
+ * tests against this interface; the daemon supplies the impl in Phase 5 (DI, ADR-3)
+ * by importing this suite from a daemon-side test. Until then it is absent and
+ * C10/C11/C12 + grant-store report `pending`. Encoding the contract here is what
+ * makes "the seam runner honours activation + gate on EVERY route" a checkable claim
+ * instead of a hope.
+ */
+interface SeamRunner {
+    /** The activation authority's verdict for a principal in a given call context. */
+    activate(principalId: string, ctx: SeamCallContext): PortInjectionResult;
+    /**
+     * The ONE grant store: the grants for this principal — NOT a hardcoded startup list
+     * (DIV-2, displaces handlers.ts:542). The gate is fed from here.
+     */
+    grantsFor(principalId: string, ctx: SeamCallContext): ReadonlySet<KernelPermissionId>;
+    /**
+     * Route an op to a contribution. MUST consult `activate()` + the gate for EVERY op,
+     * INCLUDING the `drain` subscription side-door (C10 / HOST-N2): an inactive or
+     * ungranted principal gets a typed denial and the contribution is never reached.
+     */
+    route(op: SeamRouteOp, target: {
+        readonly principalId: string;
+        readonly contributionId: string;
+    }, payload: Record<string, unknown> | undefined, ctx: SeamCallContext): Promise<SeamResponse>;
+    /** How many independent activation authorities exist. C11 demands EXACTLY ONE. */
+    activationAuthorityCount(): number;
+}
+/**
+ * The DI seams Phase-5 wires in to turn the `phase5` checks from RED→green. Every
+ * field is optional; an absent field ⇒ its dependent checks report `pending`.
+ */
+interface ConformanceWiring {
+    /** Production seam runner ⇒ enables C10, C11, C12, grant-store. */
+    readonly runner?: SeamRunner;
+    /**
+     * Override for the builder cross-validator (C15). Defaults to the shipped SDK
+     * `validateDefinitionCrossRefs` (Phase-5 slice 1 landed it in-package), so C15 is
+     * enforced without wiring; a daemon may substitute its own. Returns declaration
+     * errors for a definition (empty ⇒ valid).
+     */
+    readonly validateDefinitionCrossRefs?: (definition: ExtensionDefinition) => readonly string[];
+    /**
+     * Production registry-aware agent mint (HOST-N3) ⇒ enables agentId-registry. Must
+     * REJECT a name absent from `registry`, unlike today's `makeAgentId` (blank-only).
+     */
+    readonly mintAttestedAgent?: (attestedName: string, registry: ReadonlySet<string>) => AgentId;
+    /** The agent registry the mint validates against (and the suite seeds brains for). */
+    readonly agentRegistry?: ReadonlySet<string>;
+}
+type CheckStatus = 'pass' | 'fail' | 'pending';
+type Disposition = 'enforced' | 'phase5';
+interface CheckVerdict {
+    readonly id: string;
+    readonly title: string;
+    readonly disposition: Disposition;
+    readonly status: CheckStatus;
+    readonly notes: readonly string[];
+}
+interface ConformanceInput {
+    readonly subjects: readonly ConformanceSubject[];
+    readonly negatives: readonly NegativeFixture[];
+    readonly wiring?: ConformanceWiring;
+    /** Seed for the InMemoryHost — two agents seeded DIFFERENTLY so C2 can see variance. */
+    readonly host?: InMemoryHost;
+}
+interface ConformanceReport {
+    readonly verdicts: readonly CheckVerdict[];
+    readonly enforcedFailures: number;
+    readonly phase5Pending: number;
+    readonly phase5Regressions: number;
+    readonly negativeGaps: number;
+    readonly ok: boolean;
+}
+declare function runConformance(input: ConformanceInput): Promise<ConformanceReport>;
+/** Render the visual conformance checklist (docs/61 Principle 6). */
+declare function renderReport(report: ConformanceReport, opts?: {
+    strict?: boolean;
+}): string;
+
+/**
+ * Conformance subjects — the inputs the C1–C16 suite runs against.
+ *
+ * TWO distinct CONFORMANT reference extensions (docs/61 Phase-4 requirement: "≥2
+ * distinct reference extensions … design a second"):
+ *   • Seam Probe — the canonical multi-channel probe: reads brain + host-context, asks
+ *     host-command, has a rendering surface + a data endpoint + a composer capability.
+ *   • Notes Lens — a deliberately DIFFERENT shape: brain-only (one declared permission),
+ *     a data endpoint + a contextual action (chat/invoke), no host-context/command.
+ * Two different declared footprints and contribution kinds is what makes C2/C3/C8
+ * non-trivial — a suite over one extension can't tell "honours the contract" from
+ * "happens to match this one extension".
+ *
+ * Plus a NEGATIVE FIXTURE per check — a tiny extension built to FAIL exactly one
+ * requirement. Without these the suite is vacuous (the Phase-3 red-team's verdict on
+ * the old harness): every check here must both PASS the references AND REJECT its
+ * negative.
+ */
+
+declare const REFERENCE_EXTENSIONS: readonly ConformanceSubject[];
+declare const NEGATIVE_FIXTURES: readonly NegativeFixture[];
+
+export { BrainHit, BrainReadPort, BrainStatsView, type CheckVerdict, type ConformanceInput, type ConformanceReport, type ConformanceSubject, type ConformanceWiring, type ExtensionHostPort, type InMemoryAgentBrain, InMemoryBrainProvider, InMemoryHost, NEGATIVE_FIXTURES, type NegativeFixture, REFERENCE_EXTENSIONS, type SeamRouteOp, type SeamRunner, renderReport, runConformance };