@diyor28/context 1.0.0

package/dist/builder/context-builder.js

@@ -0,0 +1,305 @@
+"use strict";
+/**
+ * ContextBuilder: Fluent API for composing context graphs.
+ *
+ * Provides a declarative interface for building context from various sources:
+ * - System rules (pinned)
+ * - References (tool schemas, docs)
+ * - State (current workflow/session)
+ * - Memory (long-term, RAG results)
+ * - History (conversation turns)
+ * - Attachments (images, PDFs)
+ * - Current turn (user message)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextBuilder = void 0;
+const context_graph_js_1 = require("../graph/context-graph.js");
+const system_rules_codec_js_1 = require("../codecs/system-rules.codec.js");
+const conversation_history_codec_js_1 = require("../codecs/conversation-history.codec.js");
+const hash_js_1 = require("../types/hash.js");
+/**
+ * ContextBuilder: Fluent API for composing context.
+ *
+ * Usage:
+ * ```ts
+ * const builder = new ContextBuilder();
+ * builder
+ *   .system({ text: 'You are a helpful assistant.' })
+ *   .history(previousMessages)
+ *   .turn('What is the capital of France?');
+ *
+ * const compiled = await builder.compile(policy, 'anthropic');
+ * ```
+ */
+class ContextBuilder {
+    graph;
+    blockCounter;
+    constructor() {
+        this.graph = new context_graph_js_1.ContextGraph();
+        this.blockCounter = 0;
+    }
+    /**
+     * Add a pinned system rules block.
+     *
+     * @param rules - System rules payload
+     * @param options - Optional block metadata overrides
+     * @returns This builder (for chaining)
+     */
+    system(rules, options) {
+        const block = this.createBlock('pinned', system_rules_codec_js_1.SystemRulesCodec, rules, options);
+        this.graph.addBlock(block);
+        return this;
+    }
+    /**
+     * Add a reference block (tool schema, external doc, etc.).
+     *
+     * @param codec - Block codec for the reference type
+     * @param data - Reference payload
+     * @param options - Optional block metadata overrides
+     * @returns This builder (for chaining)
+     */
+    reference(codec, data, options) {
+        const block = this.createBlock('reference', codec, data, options);
+        this.graph.addBlock(block);
+        return this;
+    }
+    /**
+     * Add a state block (current workflow/session state).
+     *
+     * @param codec - Block codec for the state type
+     * @param data - State payload
+     * @param options - Optional block metadata overrides
+     * @returns This builder (for chaining)
+     */
+    state(codec, data, options) {
+        const block = this.createBlock('state', codec, data, options);
+        this.graph.addBlock(block);
+        return this;
+    }
+    /**
+     * Add a memory block (long-term memory, RAG results).
+     *
+     * @param codec - Block codec for the memory type
+     * @param data - Memory payload
+     * @param options - Optional block metadata overrides
+     * @returns This builder (for chaining)
+     */
+    memory(codec, data, options) {
+        const block = this.createBlock('memory', codec, data, options);
+        this.graph.addBlock(block);
+        return this;
+    }
+    /**
+     * Add a conversation history block.
+     *
+     * @param messages - Array of conversation messages
+     * @param summary - Optional summary of earlier messages
+     * @param options - Optional block metadata overrides
+     * @returns This builder (for chaining)
+     */
+    history(messages, summary, options) {
+        const payload = {
+            messages,
+            summary,
+        };
+        const block = this.createBlock('history', conversation_history_codec_js_1.ConversationHistoryCodec, payload, options);
+        this.graph.addBlock(block);
+        return this;
+    }
+    /**
+     * Add attachment blocks (images, PDFs, etc.).
+     * Note: Attachments need to be resolved via AttachmentResolver before compilation.
+     *
+     * @param attachments - Array of attachments
+     * @param codec - Block codec for attachment type
+     * @param options - Optional block metadata overrides
+     * @returns This builder (for chaining)
+     */
+    attachments(attachments, codec, options) {
+        // For each attachment, create a reference block
+        // The actual resolution happens via AttachmentResolver
+        for (const attachment of attachments) {
+            const block = this.createBlock('reference', codec, attachment, options);
+            this.graph.addBlock(block);
+        }
+        return this;
+    }
+    /**
+     * Add a user turn block (current user message).
+     *
+     * @param text - User message text
+     * @param options - Optional block metadata overrides
+     * @returns This builder (for chaining)
+     */
+    turn(text, options) {
+        // Use a simple text payload for turn blocks
+        const payload = { text };
+        const block = this.createBlock('turn', {
+            codecId: 'user-turn',
+            version: '1.0.0',
+            payloadSchema: {},
+            canonicalize: (p) => ({ text: p.text.trim() }),
+            hash: (c) => {
+                return (0, hash_js_1.computeBlockHash)({ kind: 'turn', sensitivity: 'public', codecId: 'user-turn', codecVersion: '1.0.0' }, c);
+            },
+            render: (block) => ({
+                anthropic: { role: 'user', content: block.payload.text },
+                openai: { role: 'user', content: block.payload.text },
+                gemini: { role: 'user', parts: [{ text: block.payload.text }] },
+            }),
+            validate: (p) => p,
+        }, payload, options);
+        this.graph.addBlock(block);
+        return this;
+    }
+    /**
+     * Create a forked context with filtering.
+     * Useful for creating specialized contexts (e.g., public-only for external models).
+     *
+     * @param options - Fork filtering options
+     * @returns New ContextBuilder with filtered blocks
+     */
+    fork(options) {
+        const forked = new ContextBuilder();
+        // Filter blocks based on options
+        const allBlocks = this.graph.getAllBlocks();
+        for (const block of allBlocks) {
+            let include = true;
+            // Sensitivity filter
+            if (options.maxSensitivity !== undefined) {
+                const sensitivityOrder = {
+                    public: 0,
+                    internal: 1,
+                    restricted: 2,
+                };
+                if (sensitivityOrder[block.meta.sensitivity] > sensitivityOrder[options.maxSensitivity]) {
+                    include = false;
+                }
+            }
+            // Kind filter (include)
+            if (options.includeKinds !== undefined) {
+                if (!options.includeKinds.includes(block.meta.kind)) {
+                    include = false;
+                }
+            }
+            // Kind filter (exclude)
+            if (options.excludeKinds !== undefined) {
+                if (options.excludeKinds.includes(block.meta.kind)) {
+                    include = false;
+                }
+            }
+            // Tag filter
+            if (options.tags !== undefined && options.tags.length > 0) {
+                const blockTags = block.meta.tags ?? [];
+                const hasMatchingTag = options.tags.some((tag) => blockTags.includes(tag));
+                if (!hasMatchingTag) {
+                    include = false;
+                }
+            }
+            if (include) {
+                forked.graph.addBlock(block, this.graph.getDerivedFrom(block.blockHash), this.graph.getReferences(block.blockHash));
+            }
+        }
+        return forked;
+    }
+    /**
+     * Compile the context for a specific provider.
+     * This is a placeholder - actual compilation happens in provider compilers.
+     *
+     * @param policy - Context policy configuration
+     * @param provider - Target provider
+     * @returns Compiled context
+     */
+    async compile(policy, provider) {
+        // This is a placeholder - the actual implementation will be in provider compilers
+        // For now, we'll just create a view and return basic structure
+        // Create a simple stub estimator (would use provider-specific estimator in production)
+        const stubEstimator = {
+            estimate: async (blocks) => ({
+                tokens: blocks.length * 100,
+                confidence: 'low',
+            }),
+            estimateBlock: async (block) => ({
+                tokens: 100,
+                confidence: 'low',
+            }),
+        };
+        const view = await this.graph.createView({
+            tokenEstimator: stubEstimator,
+            maxTokens: policy.contextWindow - policy.completionReserve,
+        });
+        return {
+            provider,
+            modelId: policy.modelId,
+            messages: [],
+            estimatedTokens: 0,
+            blocks: [...view.blocks],
+            meta: {
+                compiledAt: Math.floor(Date.now() / 1000),
+                contextWindow: policy.contextWindow,
+                completionReserve: policy.completionReserve,
+                availableTokens: policy.contextWindow - policy.completionReserve,
+                overflowed: false,
+                compacted: false,
+                truncated: false,
+                tokensByKind: {},
+            },
+        };
+    }
+    /**
+     * Get the underlying context graph.
+     *
+     * @returns Context graph
+     */
+    getGraph() {
+        return this.graph;
+    }
+    /**
+     * Get the number of blocks in the builder.
+     *
+     * @returns Block count
+     */
+    getBlockCount() {
+        return this.graph.getBlockCount();
+    }
+    /**
+     * Clear all blocks from the builder.
+     */
+    clear() {
+        this.graph.clear();
+        this.blockCounter = 0;
+    }
+    /**
+     * Create a block with generated hash and metadata.
+     *
+     * @param kind - Block kind
+     * @param codec - Block codec
+     * @param payload - Block payload
+     * @param options - Optional metadata overrides
+     * @returns Context block
+     */
+    createBlock(kind, codec, payload, options) {
+        // Validate payload
+        codec.validate(payload);
+        // Canonicalize and compute hash
+        const canonicalized = codec.canonicalize(payload);
+        const blockHash = codec.hash(canonicalized);
+        // Generate unique ID for this block instance
+        this.blockCounter++;
+        return {
+            blockHash,
+            meta: {
+                kind,
+                sensitivity: options?.sensitivity ?? 'public',
+                codecId: codec.codecId,
+                codecVersion: codec.version,
+                createdAt: Math.floor(Date.now() / 1000),
+                source: options?.source,
+                tags: options?.tags,
+            },
+            payload,
+        };
+    }
+}
+exports.ContextBuilder = ContextBuilder;
+//# sourceMappingURL=context-builder.js.map

package/dist/builder/context-builder.js.map

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

package/dist/builder/context-fork.d.ts

@@ -0,0 +1,166 @@
+/**
+ * ContextFork: Create sub-agent contexts with sensitivity enforcement.
+ *
+ * Enables forking contexts for sub-agents with automatic sensitivity redaction,
+ * budget overrides, and schema-enforced output validation.
+ */
+import { type ZodSchema } from 'zod';
+import type { ContextGraph } from '../graph/context-graph.js';
+import type { ContextView } from '../graph/views.js';
+import type { ContextBlock, SensitivityLevel } from '../types/block.js';
+import type { ModelRef } from '../types/policy.js';
+/**
+ * Sub-agent task definition with schema-enforced output.
+ */
+export interface SubAgentTask<TOutput = unknown> {
+    /** Task instruction for the sub-agent */
+    instruction: string;
+    /** Expected output schema (Zod schema, required) */
+    expectedOutputSchema: ZodSchema<TOutput>;
+    /** Maximum output tokens (optional) */
+    maxOutputTokens?: number;
+    /** Forbidden fields that must not appear in output */
+    forbiddenFields?: string[];
+}
+/**
+ * Fork options for creating sub-agent contexts.
+ */
+export interface ContextForkOptions {
+    /** Unique agent identifier */
+    agentId: string;
+    /** Human-readable fork name */
+    name: string;
+    /** Model to use for this fork */
+    model: ModelRef;
+    /** Inherit query from parent context */
+    inheritQuery?: boolean;
+    /** Include conversation history in fork */
+    includeHistory?: boolean;
+    /** Include state blocks in fork */
+    includeState?: boolean;
+    /** Maximum sensitivity level to include (default: 'public') */
+    maxSensitivity?: SensitivityLevel;
+    /** Token budget override (optional) */
+    budgetOverride?: number;
+}
+/**
+ * LLM usage statistics.
+ */
+export interface UsageStats {
+    /** Input tokens */
+    inputTokens: number;
+    /** Output tokens */
+    outputTokens: number;
+    /** Total tokens */
+    totalTokens: number;
+}
+/**
+ * Provenance information for fork result.
+ */
+export interface ForkProvenance {
+    /** Source view hash */
+    sourceViewHash: string;
+    /** Execution hash (deterministic) */
+    executionHash: string;
+    /** Fork creation timestamp */
+    forkedAt: number;
+    /** Fork completion timestamp */
+    completedAt: number;
+}
+/**
+ * Fork execution result.
+ */
+export interface ForkResult<TOutput = unknown> {
+    /** Agent ID */
+    agentId: string;
+    /** Model used */
+    model: ModelRef;
+    /** Task summary */
+    summary: string;
+    /** Structured output (validated against schema) */
+    output: TOutput;
+    /** Generated artifacts (optional) */
+    artifacts?: Array<{
+        name: string;
+        type: string;
+        content: string;
+    }>;
+    /** Citations to source blocks (block hashes) */
+    citations?: string[];
+    /** Usage statistics */
+    usage: UsageStats;
+    /** Provenance information */
+    provenance: ForkProvenance;
+}
+/**
+ * Filter view blocks by sensitivity level.
+ * Blocks exceeding maxSensitivity are replaced with redacted stubs.
+ *
+ * @param view - Source context view
+ * @param maxSensitivity - Maximum allowed sensitivity level
+ * @returns Filtered blocks with redacted stubs
+ */
+export declare function filterBySensitivity(view: ContextView, maxSensitivity: SensitivityLevel): ContextBlock<unknown>[];
+/**
+ * Compute deterministic execution hash.
+ * Hash includes: model + compiledViewHash + instruction + schemaHash + toolsetVersion
+ *
+ * @param model - Model reference
+ * @param viewHash - Compiled view hash
+ * @param instruction - Task instruction
+ * @param schemaHash - Output schema hash
+ * @param toolsetVersion - Toolset version (optional)
+ * @returns Hex-encoded SHA-256 hash
+ */
+export declare function computeExecutionHash(model: ModelRef, viewHash: string, instruction: string, schemaHash: string, toolsetVersion?: string): string;
+/**
+ * Compute schema hash for deterministic execution tracking.
+ *
+ * @param schema - Zod schema
+ * @returns Hex-encoded SHA-256 hash
+ */
+export declare function computeSchemaHash(schema: ZodSchema): string;
+/**
+ * ContextFork: Create sub-agent contexts with sensitivity enforcement.
+ */
+export declare class ContextFork {
+    private readonly graph;
+    private readonly parentView;
+    constructor(graph: ContextGraph, parentView: ContextView);
+    /**
+     * Create a fork with sensitivity filtering and budget override.
+     *
+     * @param options - Fork options
+     * @returns Filtered context view for sub-agent
+     */
+    createFork(options: ContextForkOptions): Promise<ContextView>;
+    /**
+     * Execute a sub-agent task with schema validation.
+     *
+     * @param task - Sub-agent task definition
+     * @param options - Fork options
+     * @param executor - Async executor function (calls LLM)
+     * @returns Fork result with validated output
+     */
+    executeFork<TOutput>(task: SubAgentTask<TOutput>, options: ContextForkOptions, executor: (instruction: string, view: ContextView) => Promise<{
+        output: unknown;
+        summary: string;
+        artifacts?: Array<{
+            name: string;
+            type: string;
+            content: string;
+        }>;
+        citations?: string[];
+        usage: UsageStats;
+    }>): Promise<ForkResult<TOutput>>;
+    /**
+     * Ingest fork result back into parent graph.
+     * Adds result as a memory block with provenance tracking.
+     *
+     * @param result - Fork result to ingest
+     * @param asMemory - Add as memory block (default: true)
+     * @returns Block hash of ingested result
+     */
+    ingestForkResult<TOutput>(result: ForkResult<TOutput>, asMemory?: boolean): string;
+}
+//# sourceMappingURL=context-fork.d.ts.map

package/dist/builder/context-fork.d.ts.map

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