@diyor28/context 1.0.0

package/src/codecs/redacted-stub.codec.ts

@@ -0,0 +1,76 @@
+/**
+ * Redacted stub codec (any kind).
+ *
+ * Placeholder for sensitive content that was removed.
+ */
+
+import { z } from 'zod';
+import type { BlockCodec, RenderedContent } from '../types/codec.js';
+import type { ContextBlock } from '../types/block.js';
+import { defaultHash, sortObjectKeys } from './base.js';
+
+/**
+ * Redacted stub payload schema.
+ */
+export const RedactedStubPayloadSchema = z.object({
+  /** Original block hash (for reference) */
+  originalBlockHash: z.string(),
+
+  /** Reason for redaction */
+  reason: z.string(),
+
+  /** Optional placeholder text */
+  placeholder: z.string().optional(),
+});
+
+export type RedactedStubPayload = z.infer<typeof RedactedStubPayloadSchema>;
+
+/**
+ * Redacted stub codec implementation.
+ */
+export const RedactedStubCodec: BlockCodec<RedactedStubPayload> = {
+  codecId: 'redacted-stub',
+  version: '1.0.0',
+  payloadSchema: RedactedStubPayloadSchema,
+
+  canonicalize(payload: RedactedStubPayload): unknown {
+    return sortObjectKeys({
+      originalBlockHash: payload.originalBlockHash,
+      reason: payload.reason,
+      placeholder: payload.placeholder ?? '[REDACTED]',
+    });
+  },
+
+  hash(canonicalized: unknown): string {
+    return defaultHash(canonicalized);
+  },
+
+  render(block: ContextBlock<RedactedStubPayload>): RenderedContent {
+    const { placeholder, reason } = block.payload;
+    const text = `${placeholder ?? '[REDACTED]'}\n\n*Reason: ${reason}*`;
+
+    return {
+      // Anthropic: user message
+      anthropic: {
+        role: 'user',
+        content: [{ type: 'text', text }],
+      },
+
+      // OpenAI: user message
+      openai: {
+        role: 'user',
+        content: text,
+      },
+
+      // Gemini: user message
+      gemini: {
+        role: 'user',
+        parts: [{ text }],
+      },
+    };
+  },
+
+  validate(payload: unknown): RedactedStubPayload {
+    return RedactedStubPayloadSchema.parse(payload);
+  },
+};

package/src/codecs/structured-reference.codec.ts

@@ -0,0 +1,96 @@
+/**
+ * Structured reference codec (kind: 'reference').
+ *
+ * External documentation, code snippets, API responses.
+ */
+
+import { z } from 'zod';
+import type { BlockCodec, RenderedContent } from '../types/codec.js';
+import type { ContextBlock } from '../types/block.js';
+import { defaultHash, sortObjectKeys } from './base.js';
+
+/**
+ * Structured reference payload schema.
+ */
+export const StructuredReferencePayloadSchema = z.object({
+  /** Reference title */
+  title: z.string(),
+
+  /** Reference content (markdown, code, JSON, etc.) */
+  content: z.string(),
+
+  /** Optional source URL */
+  sourceUrl: z.string().optional(),
+
+  /** Optional MIME type */
+  mimeType: z.string().optional(),
+
+  /** Optional cache control hint */
+  cacheable: z.boolean().optional(),
+});
+
+export type StructuredReferencePayload = z.infer<typeof StructuredReferencePayloadSchema>;
+
+/**
+ * Structured reference codec implementation.
+ */
+export const StructuredReferenceCodec: BlockCodec<StructuredReferencePayload> = {
+  codecId: 'structured-reference',
+  version: '1.0.0',
+  payloadSchema: StructuredReferencePayloadSchema,
+
+  canonicalize(payload: StructuredReferencePayload): unknown {
+    return sortObjectKeys({
+      title: payload.title.trim(),
+      content: payload.content,
+      sourceUrl: payload.sourceUrl ?? null,
+      mimeType: payload.mimeType ?? null,
+      cacheable: payload.cacheable ?? false,
+    });
+  },
+
+  hash(canonicalized: unknown): string {
+    return defaultHash(canonicalized);
+  },
+
+  render(block: ContextBlock<StructuredReferencePayload>): RenderedContent {
+    const { title, content, sourceUrl, cacheable } = block.payload;
+
+    // Format as markdown with optional source
+    const formattedContent = [
+      `# ${title}`,
+      sourceUrl ? `\n*Source: ${sourceUrl}*\n` : '',
+      content,
+    ].join('\n');
+
+    return {
+      // Anthropic: user message with optional cache control
+      anthropic: {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: formattedContent,
+            ...(cacheable && { cache_control: { type: 'ephemeral' } }),
+          },
+        ],
+      },
+
+      // OpenAI: user message
+      openai: {
+        role: 'user',
+        content: formattedContent,
+      },
+
+      // Gemini: user message
+      gemini: {
+        role: 'user',
+        parts: [{ text: formattedContent }],
+      },
+    };
+  },
+
+  validate(payload: unknown): StructuredReferencePayload {
+    return StructuredReferencePayloadSchema.parse(payload);
+  },
+};

package/src/codecs/system-rules.codec.ts

@@ -0,0 +1,74 @@
+/**
+ * System rules codec (kind: 'pinned').
+ *
+ * System-level instructions and constraints.
+ */
+
+import { z } from 'zod';
+import type { BlockCodec, RenderedContent } from '../types/codec.js';
+import type { ContextBlock } from '../types/block.js';
+import { defaultHash, sortObjectKeys } from './base.js';
+
+/**
+ * System rules payload schema.
+ */
+export const SystemRulesPayloadSchema = z.object({
+  /** System rules text */
+  text: z.string(),
+
+  /** Optional priority (higher = more important) */
+  priority: z.number().optional(),
+
+  /** Optional cache control hint */
+  cacheable: z.boolean().optional(),
+});
+
+export type SystemRulesPayload = z.infer<typeof SystemRulesPayloadSchema>;
+
+/**
+ * System rules codec implementation.
+ */
+export const SystemRulesCodec: BlockCodec<SystemRulesPayload> = {
+  codecId: 'system-rules',
+  version: '1.0.0',
+  payloadSchema: SystemRulesPayloadSchema,
+
+  canonicalize(payload: SystemRulesPayload): unknown {
+    // Normalize whitespace and sort keys
+    return sortObjectKeys({
+      text: payload.text.trim(),
+      priority: payload.priority ?? 0,
+      cacheable: payload.cacheable ?? false,
+    });
+  },
+
+  hash(canonicalized: unknown): string {
+    return defaultHash(canonicalized);
+  },
+
+  render(block: ContextBlock<SystemRulesPayload>): RenderedContent {
+    const { text, cacheable } = block.payload;
+
+    return {
+      // Anthropic: system message with optional cache control
+      anthropic: {
+        type: 'text',
+        text,
+        ...(cacheable && { cache_control: { type: 'ephemeral' } }),
+      },
+
+      // OpenAI: system message
+      openai: {
+        role: 'system',
+        content: text,
+      },
+
+      // Gemini: system instruction (string)
+      gemini: text,
+    };
+  },
+
+  validate(payload: unknown): SystemRulesPayload {
+    return SystemRulesPayloadSchema.parse(payload);
+  },
+};

package/src/codecs/tool-output.codec.ts

@@ -0,0 +1,109 @@
+/**
+ * Tool output codec (kind: 'tool_output').
+ *
+ * Results from tool execution.
+ */
+
+import { z } from 'zod';
+import type { BlockCodec, RenderedContent } from '../types/codec.js';
+import type { ContextBlock } from '../types/block.js';
+import { defaultHash, sortObjectKeys } from './base.js';
+
+/**
+ * Tool output payload schema.
+ */
+export const ToolOutputPayloadSchema = z.object({
+  /** Tool name */
+  toolName: z.string(),
+
+  /** Tool call ID (for correlation) */
+  toolCallId: z.string(),
+
+  /** Tool output (success or error) */
+  output: z.union([
+    z.object({
+      success: z.literal(true),
+      result: z.unknown(),
+    }),
+    z.object({
+      success: z.literal(false),
+      error: z.string(),
+    }),
+  ]),
+
+  /** Execution duration (ms) */
+  durationMs: z.number().optional(),
+});
+
+export type ToolOutputPayload = z.infer<typeof ToolOutputPayloadSchema>;
+
+/**
+ * Tool output codec implementation.
+ */
+export const ToolOutputCodec: BlockCodec<ToolOutputPayload> = {
+  codecId: 'tool-output',
+  version: '1.0.0',
+  payloadSchema: ToolOutputPayloadSchema,
+
+  canonicalize(payload: ToolOutputPayload): unknown {
+    return sortObjectKeys({
+      toolName: payload.toolName,
+      toolCallId: payload.toolCallId,
+      output: payload.output,
+      // Exclude durationMs from canonicalization (not content-relevant)
+    });
+  },
+
+  hash(canonicalized: unknown): string {
+    return defaultHash(canonicalized);
+  },
+
+  render(block: ContextBlock<ToolOutputPayload>): RenderedContent {
+    const { toolName, toolCallId, output } = block.payload;
+
+    // Format output content
+    const contentText = output.success
+      ? JSON.stringify(output.result, null, 2)
+      : `Error: ${output.error}`;
+
+    return {
+      // Anthropic: user message with tool_result
+      anthropic: {
+        role: 'user',
+        content: [
+          {
+            type: 'tool_result',
+            tool_use_id: toolCallId,
+            content: contentText,
+            is_error: !output.success,
+          },
+        ],
+      },
+
+      // OpenAI: tool message
+      openai: {
+        role: 'tool',
+        tool_call_id: toolCallId,
+        name: toolName,
+        content: contentText,
+      },
+
+      // Gemini: user message with function response
+      gemini: {
+        role: 'user',
+        parts: [
+          {
+            functionResponse: {
+              name: toolName,
+              response: output.success ? output.result : { error: output.error },
+            },
+          },
+        ],
+      },
+    };
+  },
+
+  validate(payload: unknown): ToolOutputPayload {
+    return ToolOutputPayloadSchema.parse(payload);
+  },
+};

package/src/codecs/tool-schema.codec.ts

@@ -0,0 +1,87 @@
+/**
+ * Tool schema codec (kind: 'reference').
+ *
+ * Tool definitions for function calling.
+ */
+
+import { z } from 'zod';
+import type { BlockCodec, RenderedContent } from '../types/codec.js';
+import type { ContextBlock } from '../types/block.js';
+import { defaultHash, sortObjectKeys } from './base.js';
+
+/**
+ * Tool schema payload schema (JSON Schema-like).
+ */
+export const ToolSchemaPayloadSchema = z.object({
+  /** Tool name */
+  name: z.string(),
+
+  /** Tool description */
+  description: z.string(),
+
+  /** Input schema (JSON Schema) */
+  inputSchema: z.record(z.unknown()),
+
+  /** Optional cache control hint */
+  cacheable: z.boolean().optional(),
+});
+
+export type ToolSchemaPayload = z.infer<typeof ToolSchemaPayloadSchema>;
+
+/**
+ * Tool schema codec implementation.
+ */
+export const ToolSchemaCodec: BlockCodec<ToolSchemaPayload> = {
+  codecId: 'tool-schema',
+  version: '1.0.0',
+  payloadSchema: ToolSchemaPayloadSchema,
+
+  canonicalize(payload: ToolSchemaPayload): unknown {
+    // Sort keys for deterministic hashing
+    return sortObjectKeys({
+      name: payload.name,
+      description: payload.description.trim(),
+      inputSchema: sortObjectKeys(payload.inputSchema as Record<string, unknown>),
+      cacheable: payload.cacheable ?? false,
+    });
+  },
+
+  hash(canonicalized: unknown): string {
+    return defaultHash(canonicalized);
+  },
+
+  render(block: ContextBlock<ToolSchemaPayload>): RenderedContent {
+    const { name, description, inputSchema, cacheable } = block.payload;
+
+    return {
+      // Anthropic: tool definition
+      anthropic: {
+        name,
+        description,
+        input_schema: inputSchema,
+        ...(cacheable && { cache_control: { type: 'ephemeral' } }),
+      },
+
+      // OpenAI: function definition
+      openai: {
+        type: 'function',
+        function: {
+          name,
+          description,
+          parameters: inputSchema,
+        },
+      },
+
+      // Gemini: function declaration
+      gemini: {
+        name,
+        description,
+        parameters: inputSchema,
+      },
+    };
+  },
+
+  validate(payload: unknown): ToolSchemaPayload {
+    return ToolSchemaPayloadSchema.parse(payload);
+  },
+};

package/src/codecs/unsafe-text.codec.ts

@@ -0,0 +1,74 @@
+/**
+ * Unsafe text codec (any kind).
+ *
+ * Raw text passthrough without validation. Use with caution.
+ */
+
+import { z } from 'zod';
+import type { BlockCodec, RenderedContent } from '../types/codec.js';
+import type { ContextBlock } from '../types/block.js';
+import { defaultHash } from './base.js';
+
+/**
+ * Unsafe text payload schema.
+ */
+export const UnsafeTextPayloadSchema = z.object({
+  /** Raw text content */
+  text: z.string(),
+
+  /** Optional role override (user, assistant, system) */
+  role: z.enum(['user', 'assistant', 'system']).optional(),
+});
+
+export type UnsafeTextPayload = z.infer<typeof UnsafeTextPayloadSchema>;
+
+/**
+ * Unsafe text codec implementation.
+ */
+export const UnsafeTextCodec: BlockCodec<UnsafeTextPayload> = {
+  codecId: 'unsafe-text',
+  version: '1.0.0',
+  payloadSchema: UnsafeTextPayloadSchema,
+
+  canonicalize(payload: UnsafeTextPayload): unknown {
+    // Canonicalize: trim whitespace and normalize role
+    return {
+      text: payload.text.trim(),
+      role: payload.role ?? 'user',
+    };
+  },
+
+  hash(canonicalized: unknown): string {
+    return defaultHash(canonicalized);
+  },
+
+  render(block: ContextBlock<UnsafeTextPayload>): RenderedContent {
+    const { text, role = 'user' } = block.payload;
+
+    return {
+      // Anthropic: message with specified role
+      anthropic: {
+        role: role === 'system' ? 'user' : role,
+        content: role === 'system'
+          ? [{ type: 'text', text }]
+          : text,
+      },
+
+      // OpenAI: message with specified role
+      openai: {
+        role: role === 'system' ? 'system' : role,
+        content: text,
+      },
+
+      // Gemini: convert role to user/model
+      gemini: {
+        role: role === 'assistant' ? 'model' : 'user',
+        parts: [{ text }],
+      },
+    };
+  },
+
+  validate(payload: unknown): UnsafeTextPayload {
+    return UnsafeTextPayloadSchema.parse(payload);
+  },
+};