@gixcopilot/context 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ahmed khaled
+
+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

@@ -0,0 +1,131 @@
+# @gixcopilot/context
+
+## Purpose
+
+## Install
+
+```bash
+npm install @gixcopilot/context
+```
+
+Requires Node.js >=22.12.0. ESM only.
+
+Framework-independent application context and shared state engine for the AI Copilot SDK
+(Phase 4). Lets an application tell the Copilot what it is currently looking at - and gives
+it a typed, subscribable place to keep shared state - without any dependency on React,
+Angular, or a specific LLM provider.
+
+## Responsibilities
+
+- `createContextRegistry()` — register/update/remove/list/subscribe application context
+  items, each scoped (`global`/`user`/`application`/`page`/`component`/`session`/
+  `temporary`), prioritized, and tagged with a sensitivity level.
+- `createDefaultContextSerializer()` — the controlled boundary that turns an arbitrary
+  application value into safe, model-facing text (handles `undefined`, `Date`, `bigint`,
+  circular references, functions, DOM-like nodes, class instances, and oversized
+  strings/arrays deterministically, never by throwing or emitting invalid JSON).
+- `createDefaultTokenEstimator()` — a dependency-free, provider-neutral token estimate.
+- `createTruncatingCompressor()` — the deterministic default for the `ContextCompressor`
+  extension point (a foundation for future summarization, not built in Phase 4).
+- `createContextEngine()` — the pipeline: collect → validate → serialize → filter
+  (enabled/sensitivity) → deduplicate → prioritize → budget/truncate → `ResolvedContext`,
+  plus `inspect()` for debugging what was included/excluded and why.
+- `createCopilotStateStore()` — a small, typed, subscribable shared-state store. State is a
+  distinct concept from context (see "State vs Context" below) and is never automatically
+  exposed to a model. Extended in Phase 6 with a per-slot `revision`, an opt-in
+  `modelWritable` capability flag, and a validated, non-throwing `applyPatch()` pipeline
+  (`'applied' | 'conflict' | 'rejected'`) — see "AI-writable state" below.
+
+## Public API
+
+See `src/index.ts`. No deep imports into `src/` are supported (the package's `exports`
+field only exposes `.`).
+
+## Dependencies
+
+- `@gixcopilot/protocol` — reused only for `CopilotError`, so context/state errors share the
+  SDK's one error taxonomy instead of inventing a parallel one.
+
+## Non-responsibilities
+
+- **No React/Angular.** `@gixcopilot/react`'s `useCopilotContext`/`useCopilotState` are thin
+  adapters over this package (see `docs/adr/0009-context-and-state-architecture.md`).
+- **No AI-based context selection.** Resolution is deterministic (scope/priority/budget),
+  not an extra LLM call to pick relevant context (Section 19 of the Phase 4 brief).
+- **No security enforcement.** Sensitivity metadata and the default "exclude `restricted`"
+  policy are a foundation only - never an authorization mechanism. See the security skill
+  and Phase 7.
+- **No durable memory.** `session`/`temporary` context and shared state are in-memory for
+  the life of the registry/store; nothing here persists across page loads or is Copilot
+  "memory" (a later phase's concern).
+
+## State vs Context
+
+- **State** is mutable application/Copilot data (e.g. `applicationFilters`).
+- **Context** is what has been selected/prepared for model consumption (e.g. "Current
+  filters are: status = pending").
+
+State is not automatically sent to the model. Exposing a state value to a model is an
+explicit, separate act — see `@gixcopilot/react`'s `useCopilotState({ exposeToModel })`.
+
+## Basic Usage
+
+```ts
+import { createContextRegistry, createContextEngine } from '@gixcopilot/context';
+
+const registry = createContextRegistry();
+const engine = createContextEngine({ maxContextTokens: 4000 });
+
+const registration = registry.register({
+  name: 'selectedApplication',
+  description: 'Application currently selected by the user',
+  scope: 'component',
+  priority: 'high',
+  value: { id: 'APP-1024', status: 'pending' },
+});
+
+const resolved = await engine.resolve(registry);
+console.log(resolved.content); // ready to place into a model request
+
+registration.update({ id: 'APP-1024', status: 'approved' });
+registration.dispose();
+```
+
+```ts
+import { createCopilotStateStore } from '@gixcopilot/context';
+
+const state = createCopilotStateStore();
+state.register({ id: 'filters', name: 'applicationFilters', initialValue: { status: 'all' } });
+state.subscribe('filters', (value) => console.log('filters changed', value));
+state.update('filters', (previous) => ({ ...previous, status: 'pending' }));
+```
+
+## AI-writable state (Phase 6)
+
+A slot registered with `modelWritable: true` accepts a validated, revision-checked patch —
+never a direct, untrusted write:
+
+```ts
+state.register({ id: 'filters', name: 'applicationFilters', initialValue: { status: 'all' }, modelWritable: true });
+
+const result = state.applyPatch('filters', { op: 'set', value: { status: 'pending' } }, state.getRevision('filters')!);
+// { status: 'applied', revision: 1, value: { status: 'pending' } }
+//   | { status: 'conflict', currentRevision: number }   <- baseRevision was stale
+//   | { status: 'rejected', reason: '...', detail?: string }
+```
+
+`revision` increments on **every** successful `set`/`update`/`applyPatch`, so a UI-driven
+change also invalidates a stale AI-proposed `baseRevision` — see
+`docs/adr/0011-generative-ui-and-state-patch-architecture.md`. `@gixcopilot/generative-ui`
+bridges a `modelWritable` slot into a reserved tool a model calls to propose a patch;
+`@gixcopilot/react`'s `useCopilotState({ modelWritable: true })` wires this up automatically.
+
+## Documentation
+
+- [context-and-state guide](https://github.com/AfoudaSWE/gix_ai_copilot_nx/blob/main/docs/guides/context-and-state.md)
+- [Getting started](https://github.com/AfoudaSWE/gix_ai_copilot_nx/blob/main/docs/guides/getting-started.md)
+- [Source](https://github.com/AfoudaSWE/gix_ai_copilot_nx/tree/main/packages/context)
+
+## License
+
+MIT

package/dist/context-compressor.d.ts

@@ -0,0 +1,28 @@
+import type { TokenEstimator } from './token-estimator.js';
+/** The minimal shape a compressor operates on - already-serialized text plus its cost. */
+export interface CompressibleText {
+    readonly text: string;
+    readonly estimatedTokens: number;
+}
+/**
+ * The compression extension point (Section 29). Phase 4 ships only a deterministic
+ * truncating implementation (`createTruncatingCompressor`); the interface is async-capable
+ * so a future phase can plug in an LLM-based summarizer for a single over-budget item
+ * without changing `ContextEngine`'s pipeline.
+ *
+ * Deliberately narrower than a whole-`SerializedContext` compressor: `ContextEngine`
+ * (`context-engine.ts`) already performs whole-context priority/budget selection itself
+ * (Section 23, 27) and only reaches for a compressor when one *individual* item's own text
+ * does not fit in whatever budget remains for it - see `Phase_4_Decisions.md`.
+ */
+export interface ContextCompressor {
+    compress(input: CompressibleText, budgetTokens: number): Promise<CompressibleText> | CompressibleText;
+}
+/**
+ * Deterministically shrinks `text` toward `budgetTokens` using the supplied (or default)
+ * estimator, by iteratively resizing proportionally to the estimator's own ratio rather
+ * than assuming a fixed chars-per-token constant - keeps this correct for any pluggable
+ * estimator, not just the default heuristic.
+ */
+export declare function createTruncatingCompressor(estimator?: TokenEstimator): ContextCompressor;
+//# sourceMappingURL=context-compressor.d.ts.map

package/dist/context-compressor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-compressor.d.ts","sourceRoot":"","sources":["../src/context-compressor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,0FAA0F;AAC1F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAAC;CACvG;AAID;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,GAAE,cAA8C,GAAG,iBAAiB,CA6BvH"}

package/dist/context-compressor.js

@@ -0,0 +1,35 @@
+import { createDefaultTokenEstimator } from './token-estimator.js';
+const TRUNCATION_MARKER = '\n…(truncated to fit context budget)';
+/**
+ * Deterministically shrinks `text` toward `budgetTokens` using the supplied (or default)
+ * estimator, by iteratively resizing proportionally to the estimator's own ratio rather
+ * than assuming a fixed chars-per-token constant - keeps this correct for any pluggable
+ * estimator, not just the default heuristic.
+ */
+export function createTruncatingCompressor(estimator = createDefaultTokenEstimator()) {
+    return {
+        compress(input, budgetTokens) {
+            if (budgetTokens <= 0) {
+                return { text: '', estimatedTokens: 0 };
+            }
+            if (input.estimatedTokens <= budgetTokens) {
+                return input;
+            }
+            let text = input.text;
+            for (let attempt = 0; attempt < 6; attempt++) {
+                const currentTokens = estimator.estimate(text);
+                if (currentTokens <= budgetTokens) {
+                    return { text, estimatedTokens: currentTokens };
+                }
+                const ratio = Math.max(0, budgetTokens / currentTokens);
+                const targetLength = Math.max(0, Math.floor(text.length * ratio) - TRUNCATION_MARKER.length);
+                if (targetLength <= 0) {
+                    return { text: '', estimatedTokens: 0 };
+                }
+                text = text.slice(0, targetLength) + TRUNCATION_MARKER;
+            }
+            return { text, estimatedTokens: estimator.estimate(text) };
+        },
+    };
+}
+//# sourceMappingURL=context-compressor.js.map

package/dist/context-compressor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-compressor.js","sourceRoot":"","sources":["../src/context-compressor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AAuBnE,MAAM,iBAAiB,GAAG,sCAAsC,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,YAA4B,2BAA2B,EAAE;IAClG,OAAO;QACL,QAAQ,CAAC,KAAuB,EAAE,YAAoB;YACpD,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;gBACtB,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;YAC1C,CAAC;YACD,IAAI,KAAK,CAAC,eAAe,IAAI,YAAY,EAAE,CAAC;gBAC1C,OAAO,KAAK,CAAC;YACf,CAAC;YAED,IAAI,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;YACtB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC;gBAC7C,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;gBAC/C,IAAI,aAAa,IAAI,YAAY,EAAE,CAAC;oBAClC,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,aAAa,EAAE,CAAC;gBAClD,CAAC;gBACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC;gBACxD,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAC3B,CAAC,EACD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,GAAG,iBAAiB,CAAC,MAAM,CAC3D,CAAC;gBACF,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;oBACtB,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;gBAC1C,CAAC;gBACD,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,GAAG,iBAAiB,CAAC;YACzD,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7D,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/context-engine.d.ts

@@ -0,0 +1,36 @@
+import type { ContextRegistry } from './context-registry.js';
+import type { CopilotContextItem } from './context-item.js';
+import type { ContextSerializer } from './context-serializer.js';
+import type { TokenEstimator } from './token-estimator.js';
+import type { ContextCompressor } from './context-compressor.js';
+import type { ContextInspection, ResolvedContext } from './resolved-context.js';
+export interface ContextEngineOptions {
+    /** Filters structured values before serialization or truncation. Throws fail closed per item. */
+    readonly dataPolicy?: {
+        redact(data: unknown): unknown;
+    };
+    /** Total token budget resolved context may consume. Default 8000 (Section 25). */
+    readonly maxContextTokens?: number;
+    readonly estimator?: TokenEstimator;
+    readonly serializer?: ContextSerializer;
+    readonly compressor?: ContextCompressor;
+    /**
+     * Returns `true` if an item is allowed to reach the model. Defaults to excluding
+     * `restricted` items. This is a conservative default, not a security boundary (Section 30,
+     * 58) - Phase 7 owns real sensitivity/PII enforcement.
+     */
+    readonly sensitivityPolicy?: (item: CopilotContextItem) => boolean;
+}
+/**
+ * The central pipeline: Registry -> Collect -> Validate -> Serialize -> Filter ->
+ * Deduplicate -> Prioritize -> Budget -> Resolved Context (Section 23). One registry's
+ * worth of items in, one `ResolvedContext` out - stateless with respect to the registry, so
+ * one engine can safely serve many isolated registries (Section 65).
+ */
+export interface ContextEngine {
+    resolve(registry: ContextRegistry): Promise<ResolvedContext>;
+    /** Debug-friendly projection of `resolve()`, for future DevTools (Section 57, 90). */
+    inspect(registry: ContextRegistry): Promise<ContextInspection>;
+}
+export declare function createContextEngine(options?: ContextEngineOptions): ContextEngine;
+//# sourceMappingURL=context-engine.d.ts.map

package/dist/context-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-engine.d.ts","sourceRoot":"","sources":["../src/context-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAGjE,OAAO,KAAK,EAGV,iBAAiB,EACjB,eAAe,EAEhB,MAAM,uBAAuB,CAAC;AAM/B,MAAM,WAAW,oBAAoB;IACnC,iGAAiG;IACjG,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAE,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,CAAC;IACzD,kFAAkF;IAClF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,OAAO,CAAC;CACpE;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC7D,sFAAsF;IACtF,OAAO,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChE;AAcD,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,aAAa,CAmLrF"}

package/dist/context-engine.js

@@ -0,0 +1,191 @@
+import { priorityWeight } from './context-priority.js';
+import { createDefaultContextSerializer } from './context-serializer.js';
+import { createDefaultTokenEstimator } from './token-estimator.js';
+import { createTruncatingCompressor } from './context-compressor.js';
+import { formatContextItemBlock, joinContextBlocks } from './context-format.js';
+const DEFAULT_MAX_CONTEXT_TOKENS = 8000;
+/** Smallest remaining budget the engine will bother compressing an item into (Section 28). */
+const MIN_COMPRESSIBLE_BUDGET_TOKENS = 16;
+function defaultSensitivityPolicy(item) {
+    return item.sensitivity !== 'restricted';
+}
+export function createContextEngine(options = {}) {
+    const maxContextTokens = options.maxContextTokens ?? DEFAULT_MAX_CONTEXT_TOKENS;
+    const estimator = options.estimator ?? createDefaultTokenEstimator();
+    const serializer = options.serializer ?? createDefaultContextSerializer();
+    const compressor = options.compressor ?? createTruncatingCompressor(estimator);
+    const sensitivityPolicy = options.sensitivityPolicy ?? defaultSensitivityPolicy;
+    async function resolve(registry) {
+        const startedAt = Date.now();
+        const allItems = registry.list();
+        const exclusions = [];
+        const candidates = [];
+        for (const item of allItems) {
+            // No runtime "invalid" check here: `ContextRegistry.register/update/patch` already
+            // reject a blank name at admission time, so every item reaching this loop is
+            // structurally valid. The `'invalid'` exclusion reason stays part of the type (Section
+            // 35) for a future validated-input path (e.g. schema-checked registration) rather than
+            // being exercised by dead code today - see Phase_4_Decisions.md.
+            if (!item.enabled) {
+                exclusions.push({ id: item.id, name: item.name, scope: item.scope, reason: 'disabled' });
+                continue;
+            }
+            if (!sensitivityPolicy(item)) {
+                exclusions.push({
+                    id: item.id,
+                    name: item.name,
+                    scope: item.scope,
+                    reason: 'sensitivity-policy',
+                });
+                continue;
+            }
+            try {
+                const serialized = serializer.serialize(options.dataPolicy ? options.dataPolicy.redact(item.value) : item.value);
+                const text = formatContextItemBlock(item.name, item.scope, item.description, serialized.text);
+                candidates.push({
+                    item,
+                    text,
+                    estimatedTokens: estimator.estimate(text),
+                    truncated: serialized.truncated,
+                    dedupeKey: serialized.text,
+                });
+            }
+            catch (error) {
+                exclusions.push({
+                    id: item.id,
+                    name: item.name,
+                    scope: item.scope,
+                    reason: 'serialization-failure',
+                    detail: error instanceof Error ? error.message : 'Unknown serialization error.',
+                });
+            }
+        }
+        // Deduplication (Section 24): identical serialized *values* collapse to the
+        // highest-priority (then earliest-registered) candidate; the rest are excluded as
+        // 'duplicate'. Comparing the serialized text is a deliberate identity/hash check, not a
+        // fuzzy similarity guess.
+        const bestByKey = new Map();
+        for (const candidate of candidates) {
+            const existing = bestByKey.get(candidate.dedupeKey);
+            if (!existing || priorityWeight(candidate.item.priority) < priorityWeight(existing.item.priority)) {
+                bestByKey.set(candidate.dedupeKey, candidate);
+            }
+        }
+        const deduped = [];
+        for (const candidate of candidates) {
+            if (bestByKey.get(candidate.dedupeKey) === candidate) {
+                deduped.push(candidate);
+            }
+            else {
+                exclusions.push({
+                    id: candidate.item.id,
+                    name: candidate.item.name,
+                    scope: candidate.item.scope,
+                    reason: 'duplicate',
+                });
+            }
+        }
+        // Prioritize (Section 20, 27): stable sort by explicit priority tier only.
+        const prioritized = deduped
+            .map((candidate, index) => ({ candidate, index }))
+            .sort((a, b) => {
+            const byPriority = priorityWeight(a.candidate.item.priority) - priorityWeight(b.candidate.item.priority);
+            return byPriority !== 0 ? byPriority : a.index - b.index;
+        })
+            .map((entry) => entry.candidate);
+        // Budget allocation with safe truncation (Section 27, 28): include while budget
+        // remains; an item that doesn't fit is compressed toward the remaining budget before
+        // being excluded outright.
+        const resolvedItems = [];
+        let remaining = maxContextTokens;
+        for (const candidate of prioritized) {
+            if (remaining <= 0) {
+                exclusions.push({
+                    id: candidate.item.id,
+                    name: candidate.item.name,
+                    scope: candidate.item.scope,
+                    reason: 'budget',
+                });
+                continue;
+            }
+            if (candidate.estimatedTokens <= remaining) {
+                resolvedItems.push(toResolvedItem(candidate));
+                remaining -= candidate.estimatedTokens;
+                continue;
+            }
+            // Below this, compressing would only produce a near-useless fragment - exclude
+            // outright instead of "including" a scrap of text (Section 28). Only a remaining
+            // budget worth compressing into is worth spending the compressor call on.
+            if (remaining < MIN_COMPRESSIBLE_BUDGET_TOKENS) {
+                exclusions.push({
+                    id: candidate.item.id,
+                    name: candidate.item.name,
+                    scope: candidate.item.scope,
+                    reason: 'budget',
+                });
+                continue;
+            }
+            const compressed = await compressor.compress({ text: candidate.text, estimatedTokens: candidate.estimatedTokens }, remaining);
+            if (compressed.estimatedTokens > 0 && compressed.estimatedTokens <= remaining) {
+                resolvedItems.push(toResolvedItem({ ...candidate, text: compressed.text, estimatedTokens: compressed.estimatedTokens, truncated: true }));
+                remaining -= compressed.estimatedTokens;
+            }
+            else {
+                exclusions.push({
+                    id: candidate.item.id,
+                    name: candidate.item.name,
+                    scope: candidate.item.scope,
+                    reason: 'budget',
+                });
+            }
+        }
+        const content = joinContextBlocks(resolvedItems.map((item) => item.text));
+        const diagnostics = {
+            itemsRegistered: allItems.length,
+            itemsIncluded: resolvedItems.length,
+            itemsExcluded: exclusions.length,
+            resolutionMs: Date.now() - startedAt,
+        };
+        return {
+            items: resolvedItems,
+            content,
+            estimatedTokens: content ? estimator.estimate(content) : 0,
+            excluded: exclusions,
+            diagnostics,
+        };
+    }
+    async function inspect(registry) {
+        const resolved = await resolve(registry);
+        return {
+            estimatedTokens: resolved.estimatedTokens,
+            included: resolved.items.map((item) => ({
+                name: item.name,
+                scope: item.scope,
+                priority: item.priority,
+                estimatedTokens: item.estimatedTokens,
+                truncated: item.truncated,
+            })),
+            excluded: resolved.excluded.map((exclusion) => ({
+                name: exclusion.name,
+                scope: exclusion.scope,
+                reason: exclusion.reason,
+            })),
+            diagnostics: resolved.diagnostics,
+        };
+    }
+    return { resolve, inspect };
+}
+function toResolvedItem(candidate) {
+    return {
+        id: candidate.item.id,
+        name: candidate.item.name,
+        description: candidate.item.description,
+        scope: candidate.item.scope,
+        priority: candidate.item.priority,
+        sensitivity: candidate.item.sensitivity,
+        estimatedTokens: candidate.estimatedTokens,
+        truncated: candidate.truncated,
+        text: candidate.text,
+    };
+}
+//# sourceMappingURL=context-engine.js.map

package/dist/context-engine.js.map

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

package/dist/context-format.d.ts

@@ -0,0 +1,10 @@
+import type { ContextScope } from './context-scope.js';
+/**
+ * Renders one item's stable, structured, model-facing block (Section 22). This is the only
+ * place prompt text is assembled for a context item - application code registers structured
+ * data; it never hand-formats a prompt string itself (see the context-engine skill).
+ */
+export declare function formatContextItemBlock(name: string, scope: ContextScope, description: string | undefined, serializedText: string): string;
+/** Joins already-formatted item blocks into the single content string sent with a run. */
+export declare function joinContextBlocks(blocks: readonly string[]): string;
+//# sourceMappingURL=context-format.d.ts.map

package/dist/context-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-format.d.ts","sourceRoot":"","sources":["../src/context-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,YAAY,EACnB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,cAAc,EAAE,MAAM,GACrB,MAAM,CAIR;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEnE"}

package/dist/context-format.js

@@ -0,0 +1,16 @@
+/**
+ * Renders one item's stable, structured, model-facing block (Section 22). This is the only
+ * place prompt text is assembled for a context item - application code registers structured
+ * data; it never hand-formats a prompt string itself (see the context-engine skill).
+ */
+export function formatContextItemBlock(name, scope, description, serializedText) {
+    const lines = [`[Context: ${name}]`, `Scope: ${scope}`];
+    if (description)
+        lines.push(`Description: ${description}`);
+    return `${lines.join('\n')}\n\n${serializedText}`;
+}
+/** Joins already-formatted item blocks into the single content string sent with a run. */
+export function joinContextBlocks(blocks) {
+    return blocks.join('\n\n---\n\n');
+}
+//# sourceMappingURL=context-format.js.map

package/dist/context-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-format.js","sourceRoot":"","sources":["../src/context-format.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAY,EACZ,KAAmB,EACnB,WAA+B,EAC/B,cAAsB;IAEtB,MAAM,KAAK,GAAG,CAAC,aAAa,IAAI,GAAG,EAAE,UAAU,KAAK,EAAE,CAAC,CAAC;IACxD,IAAI,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,gBAAgB,WAAW,EAAE,CAAC,CAAC;IAC3D,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,cAAc,EAAE,CAAC;AACpD,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,iBAAiB,CAAC,MAAyB;IACzD,OAAO,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AACpC,CAAC"}

package/dist/context-item.d.ts

@@ -0,0 +1,44 @@
+import type { ContextPriority } from './context-priority.js';
+import type { ContextScope } from './context-scope.js';
+import type { ContextSensitivity } from './context-sensitivity.js';
+/** Free-form, serializable metadata a caller can attach for debugging (Section 34). */
+export type ContextItemMetadata = Readonly<Record<string, unknown>>;
+/**
+ * A framework-independent, transport-ready context item (Section 7). `value` is arbitrary
+ * application data at registration time; it only becomes model-facing text after passing
+ * through the engine's serializer (`context-serializer.ts`) - registering an item never
+ * hands a raw object to a model.
+ */
+export interface CopilotContextItem<T = unknown> {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly scope: ContextScope;
+    readonly value: T;
+    readonly priority: ContextPriority;
+    readonly sensitivity: ContextSensitivity;
+    /** Disabled items are stored but never reach `ContextEngine.resolve()` (Section 31). */
+    readonly enabled: boolean;
+    /** Free-form origin label (e.g. `'react-component'`) - never a framework object (Section 39). */
+    readonly owner?: string;
+    readonly metadata?: ContextItemMetadata;
+}
+/**
+ * What a caller passes to `ContextRegistry.register()`. `id` is optional - see
+ * `context-registry.ts` for the identity/deduplication rule (Section 18) it triggers.
+ */
+export interface ContextItemInput<T = unknown> {
+    readonly id?: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly scope: ContextScope;
+    readonly value: T;
+    readonly priority?: ContextPriority;
+    readonly sensitivity?: ContextSensitivity;
+    readonly enabled?: boolean;
+    readonly owner?: string;
+    readonly metadata?: ContextItemMetadata;
+}
+/** A partial update applied in place by `ContextRegistration.update()` (Section 17, 38). */
+export type ContextItemPatch<T = unknown> = Partial<Omit<ContextItemInput<T>, 'id'>>;
+//# sourceMappingURL=context-item.d.ts.map

package/dist/context-item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-item.d.ts","sourceRoot":"","sources":["../src/context-item.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,uFAAuF;AACvF,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,OAAO;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,iGAAiG;IACjG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CACzC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC3C,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CACzC;AAED,4FAA4F;AAC5F,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC"}

package/dist/context-item.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context-item.js.map

package/dist/context-item.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-item.js","sourceRoot":"","sources":["../src/context-item.ts"],"names":[],"mappings":""}

package/dist/context-priority.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Explicit context priority (Section 20). A closed set of four tiers, not a numeric scale -
+ * numeric priority invites meaningless fine-grained comparisons ("47 vs 48") with no
+ * documented semantics. Priority affects budget selection only; it is never a security
+ * boundary (see Section 20 and the security skill).
+ */
+export type ContextPriority = 'critical' | 'high' | 'normal' | 'low';
+export declare const CONTEXT_PRIORITIES: readonly ContextPriority[];
+export declare const DEFAULT_CONTEXT_PRIORITY: ContextPriority;
+/** Lower is more important. Used to sort items before budget allocation (Section 27). */
+export declare function priorityWeight(priority: ContextPriority): number;
+export declare function isContextPriority(value: unknown): value is ContextPriority;
+//# sourceMappingURL=context-priority.d.ts.map

package/dist/context-priority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-priority.d.ts","sourceRoot":"","sources":["../src/context-priority.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAErE,eAAO,MAAM,kBAAkB,EAAE,SAAS,eAAe,EAA0C,CAAC;AAEpG,eAAO,MAAM,wBAAwB,EAAE,eAA0B,CAAC;AASlE,yFAAyF;AACzF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAEhE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E"}

package/dist/context-priority.js

@@ -0,0 +1,16 @@
+export const CONTEXT_PRIORITIES = ['critical', 'high', 'normal', 'low'];
+export const DEFAULT_CONTEXT_PRIORITY = 'normal';
+const PRIORITY_WEIGHT = {
+    critical: 0,
+    high: 1,
+    normal: 2,
+    low: 3,
+};
+/** Lower is more important. Used to sort items before budget allocation (Section 27). */
+export function priorityWeight(priority) {
+    return PRIORITY_WEIGHT[priority];
+}
+export function isContextPriority(value) {
+    return typeof value === 'string' && CONTEXT_PRIORITIES.includes(value);
+}
+//# sourceMappingURL=context-priority.js.map

package/dist/context-priority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-priority.js","sourceRoot":"","sources":["../src/context-priority.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,kBAAkB,GAA+B,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;AAEpG,MAAM,CAAC,MAAM,wBAAwB,GAAoB,QAAQ,CAAC;AAElE,MAAM,eAAe,GAA8C;IACjE,QAAQ,EAAE,CAAC;IACX,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,GAAG,EAAE,CAAC;CACP,CAAC;AAEF,yFAAyF;AACzF,MAAM,UAAU,cAAc,CAAC,QAAyB;IACtD,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,kBAAwC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAChG,CAAC"}