cognitive-core 0.1.0 → 0.2.0

package/references/agent-workspace/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "agent-workspace",
+  "version": "0.1.3",
+  "description": "Filesystem workspace management for agents — directory structure, typed I/O, and validation",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "version:patch": "npm version patch && git push && git push --tags",
+    "version:minor": "npm version minor && git push && git push --tags",
+    "version:major": "npm version major && git push && git push --tags",
+    "publish:npm": "npm run build && npm publish"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alexngai/agent-workspace.git"
+  },
+  "license": "MIT",
+  "author": "Alex Ngai",
+  "dependencies": {
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^3.0.0"
+  }
+}

package/references/agent-workspace/src/handle.ts

@@ -0,0 +1,122 @@
+import * as path from 'path';
+import { writeJson, writeJsonl } from './writers/json.js';
+import { writeMarkdown } from './writers/markdown.js';
+import { writeRaw, copyDir, symlink } from './writers/raw.js';
+import { readJson, readJsonl, readJsonDir, type ReadJsonOptions } from './readers/json.js';
+import { readMarkdown, type ReadMarkdownOptions } from './readers/markdown.js';
+import { readRaw, listFiles } from './readers/raw.js';
+import { validateOutput } from './validation.js';
+import type { MarkdownDocument, OutputSpec, ValidationResult } from './types.js';
+
+export class WorkspaceHandle {
+  readonly id: string;
+  readonly path: string;
+  readonly createdAt: Date;
+  private readonly dirs: string[];
+
+  constructor(id: string, workspacePath: string, dirs: string[], createdAt: Date) {
+    this.id = id;
+    this.path = workspacePath;
+    this.dirs = dirs;
+    this.createdAt = createdAt;
+  }
+
+  /** Get the absolute path to a section directory. */
+  dir(section: string): string {
+    if (!this.dirs.includes(section)) {
+      throw new Error(
+        `Unknown section "${section}". Available: ${this.dirs.join(', ')}`,
+      );
+    }
+    return path.join(this.path, section);
+  }
+
+  // -- Convenience accessors for default dirs --
+
+  get inputDir(): string {
+    return path.join(this.path, 'input');
+  }
+  get outputDir(): string {
+    return path.join(this.path, 'output');
+  }
+  get resourcesDir(): string {
+    return path.join(this.path, 'resources');
+  }
+  get scratchDir(): string {
+    return path.join(this.path, 'scratch');
+  }
+
+  // -- Writers --
+
+  async writeJson(section: string, filePath: string, data: unknown): Promise<void> {
+    return writeJson(this.dir(section), filePath, data);
+  }
+
+  async writeJsonl(section: string, filePath: string, items: unknown[]): Promise<void> {
+    return writeJsonl(this.dir(section), filePath, items);
+  }
+
+  async writeMarkdown(section: string, filePath: string, doc: MarkdownDocument): Promise<void> {
+    return writeMarkdown(this.dir(section), filePath, doc);
+  }
+
+  async writeRaw(section: string, filePath: string, content: string): Promise<void> {
+    return writeRaw(this.dir(section), filePath, content);
+  }
+
+  async copyDir(section: string, destName: string, srcPath: string): Promise<void> {
+    return copyDir(this.dir(section), destName, srcPath);
+  }
+
+  async symlink(section: string, linkName: string, targetPath: string): Promise<void> {
+    return symlink(this.dir(section), linkName, targetPath);
+  }
+
+  // -- Readers --
+
+  async readJson<T = unknown>(
+    section: string,
+    filePath: string,
+    options?: ReadJsonOptions<T>,
+  ): Promise<T> {
+    return readJson(this.dir(section), filePath, options);
+  }
+
+  async readJsonl<T = unknown>(
+    section: string,
+    filePath: string,
+    options?: ReadJsonOptions<T>,
+  ): Promise<T[]> {
+    return readJsonl(this.dir(section), filePath, options);
+  }
+
+  async readMarkdown<T = Record<string, unknown>>(
+    section: string,
+    filePath: string,
+    options?: ReadMarkdownOptions<T>,
+  ): Promise<MarkdownDocument<T>> {
+    return readMarkdown(this.dir(section), filePath, options);
+  }
+
+  async readRaw(section: string, filePath: string): Promise<string> {
+    return readRaw(this.dir(section), filePath);
+  }
+
+  async listFiles(section: string, subPath: string = ''): Promise<string[]> {
+    return listFiles(this.dir(section), subPath);
+  }
+
+  async readJsonDir<T = unknown>(
+    section: string,
+    subPath: string,
+    options?: ReadJsonOptions<T>,
+  ): Promise<Map<string, T>> {
+    return readJsonDir(this.dir(section), subPath, options);
+  }
+
+  // -- Validation --
+
+  async validateOutput(spec: OutputSpec): Promise<ValidationResult> {
+    return validateOutput(this.outputDir, spec);
+  }
+}

package/references/agent-workspace/src/index.ts

@@ -0,0 +1,32 @@
+// Core classes
+export { WorkspaceManager } from './manager.js';
+export { WorkspaceHandle } from './handle.js';
+
+// Validation
+export { validateOutput } from './validation.js';
+
+// Standalone writer functions (for consumers who manage their own dirs)
+export { writeJson, writeJsonl } from './writers/json.js';
+export { writeMarkdown } from './writers/markdown.js';
+export { writeRaw, copyDir, symlink } from './writers/raw.js';
+
+// Standalone reader functions
+export { readJson, readJsonl, readJsonDir } from './readers/json.js';
+export { readMarkdown } from './readers/markdown.js';
+export { readRaw, listFiles } from './readers/raw.js';
+
+// Types
+export type {
+  Schema,
+  CreateWorkspaceOptions,
+  WorkspaceManagerConfig,
+  WorkspaceMeta,
+  MarkdownDocument,
+  OutputFileSpec,
+  OutputSpec,
+  ValidationError,
+  ValidationResult,
+} from './types.js';
+
+export type { ReadJsonOptions } from './readers/json.js';
+export type { ReadMarkdownOptions } from './readers/markdown.js';

package/references/agent-workspace/src/manager.ts

@@ -0,0 +1,102 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import * as crypto from 'crypto';
+import { WorkspaceHandle } from './handle.js';
+import type { CreateWorkspaceOptions, WorkspaceManagerConfig, WorkspaceMeta } from './types.js';
+
+const DEFAULT_DIRS = ['input', 'output', 'resources', 'scratch'];
+const META_FILE = '.workspace.json';
+
+export class WorkspaceManager {
+  private readonly baseDir: string;
+  private readonly prefix: string;
+
+  constructor(config: WorkspaceManagerConfig = {}) {
+    this.baseDir = config.baseDir ?? os.tmpdir();
+    this.prefix = config.prefix ?? 'agent-workspaces';
+  }
+
+  /** Root directory that contains all workspaces. */
+  private get root(): string {
+    return path.join(this.baseDir, this.prefix);
+  }
+
+  /** Create a new workspace with standard + optional additional directories. */
+  async create(taskType: string, options: CreateWorkspaceOptions = {}): Promise<WorkspaceHandle> {
+    const id = `${taskType}-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`;
+    const workspacePath = path.join(this.root, id);
+
+    const allDirs = [...DEFAULT_DIRS, ...(options.additionalDirs ?? [])];
+
+    // Create all directories in parallel
+    await fs.mkdir(workspacePath, { recursive: true });
+    await Promise.all(
+      allDirs.map((dir) => fs.mkdir(path.join(workspacePath, dir), { recursive: true })),
+    );
+
+    const meta: WorkspaceMeta = {
+      id,
+      taskType,
+      createdAt: new Date().toISOString(),
+      dirs: allDirs,
+    };
+
+    await fs.writeFile(path.join(workspacePath, META_FILE), JSON.stringify(meta, null, 2));
+
+    return new WorkspaceHandle(id, workspacePath, allDirs, new Date(meta.createdAt));
+  }
+
+  /** Remove a workspace from disk. */
+  async cleanup(handle: WorkspaceHandle): Promise<void> {
+    await fs.rm(handle.path, { recursive: true, force: true });
+  }
+
+  /** List all workspace handles under the managed root. */
+  async list(): Promise<WorkspaceHandle[]> {
+    try {
+      const entries = await fs.readdir(this.root, { withFileTypes: true });
+      const handles: WorkspaceHandle[] = [];
+
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const metaPath = path.join(this.root, entry.name, META_FILE);
+        try {
+          const raw = await fs.readFile(metaPath, 'utf-8');
+          const meta: WorkspaceMeta = JSON.parse(raw);
+          handles.push(
+            new WorkspaceHandle(
+              meta.id,
+              path.join(this.root, entry.name),
+              meta.dirs,
+              new Date(meta.createdAt),
+            ),
+          );
+        } catch {
+          // Skip directories without valid metadata
+        }
+      }
+
+      return handles;
+    } catch {
+      // Root doesn't exist yet — no workspaces
+      return [];
+    }
+  }
+
+  /** Remove workspaces older than `maxAgeMs` milliseconds. */
+  async pruneStale(maxAgeMs: number): Promise<number> {
+    const handles = await this.list();
+    const cutoff = Date.now() - maxAgeMs;
+    let pruned = 0;
+
+    for (const handle of handles) {
+      if (handle.createdAt.getTime() <= cutoff) {
+        await this.cleanup(handle);
+        pruned++;
+      }
+    }
+
+    return pruned;
+  }
+}

package/references/agent-workspace/src/readers/json.ts

@@ -0,0 +1,71 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import type { Schema } from '../types.js';
+
+export interface ReadJsonOptions<T = unknown> {
+  schema?: Schema<T>;
+}
+
+/** Read and parse a JSON file. Optionally validate against a schema. */
+export async function readJson<T = unknown>(
+  dir: string,
+  filePath: string,
+  options?: ReadJsonOptions<T>,
+): Promise<T> {
+  const fullPath = path.join(dir, filePath);
+  const raw = await fs.readFile(fullPath, 'utf-8');
+  const data = JSON.parse(raw);
+
+  if (options?.schema) {
+    return options.schema.parse(data);
+  }
+
+  return data as T;
+}
+
+/** Read a JSONL file and return an array of parsed objects. Optionally validate each item. */
+export async function readJsonl<T = unknown>(
+  dir: string,
+  filePath: string,
+  options?: ReadJsonOptions<T>,
+): Promise<T[]> {
+  const fullPath = path.join(dir, filePath);
+  const raw = await fs.readFile(fullPath, 'utf-8');
+  const lines = raw.trimEnd().split('\n').filter((line) => line.length > 0);
+
+  return lines.map((line, index) => {
+    const data = JSON.parse(line);
+    if (options?.schema) {
+      try {
+        return options.schema.parse(data);
+      } catch (err) {
+        throw new Error(
+          `JSONL validation failed at line ${index + 1}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+    return data as T;
+  });
+}
+
+/**
+ * Read all JSON files in a directory, returning a Map of filename → parsed content.
+ * Optionally validate each file against a schema.
+ */
+export async function readJsonDir<T = unknown>(
+  dir: string,
+  subPath: string,
+  options?: ReadJsonOptions<T>,
+): Promise<Map<string, T>> {
+  const fullDir = path.join(dir, subPath);
+  const entries = await fs.readdir(fullDir);
+  const result = new Map<string, T>();
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.json')) continue;
+    const data = await readJson<T>(fullDir, entry, options);
+    result.set(entry, data);
+  }
+
+  return result;
+}

package/references/agent-workspace/src/readers/markdown.ts

@@ -0,0 +1,37 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { parse as yamlParse } from 'yaml';
+import type { MarkdownDocument, Schema } from '../types.js';
+
+export interface ReadMarkdownOptions<T = Record<string, unknown>> {
+  /** Schema to validate/parse the frontmatter. */
+  frontmatterSchema?: Schema<T>;
+}
+
+/** Read a markdown file, parsing YAML frontmatter if present. */
+export async function readMarkdown<T = Record<string, unknown>>(
+  dir: string,
+  filePath: string,
+  options?: ReadMarkdownOptions<T>,
+): Promise<MarkdownDocument<T>> {
+  const fullPath = path.join(dir, filePath);
+  const raw = await fs.readFile(fullPath, 'utf-8');
+
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n\n?([\s\S]*)$/);
+
+  let frontmatter: T;
+  let body: string;
+
+  if (match) {
+    const parsed = yamlParse(match[1]);
+    frontmatter = options?.frontmatterSchema ? options.frontmatterSchema.parse(parsed) : parsed;
+    body = match[2];
+  } else {
+    frontmatter = (options?.frontmatterSchema
+      ? options.frontmatterSchema.parse({})
+      : {}) as T;
+    body = raw;
+  }
+
+  return { frontmatter, body };
+}

package/references/agent-workspace/src/readers/raw.ts

@@ -0,0 +1,27 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+/** Read a file as a raw string. */
+export async function readRaw(dir: string, filePath: string): Promise<string> {
+  const fullPath = path.join(dir, filePath);
+  return fs.readFile(fullPath, 'utf-8');
+}
+
+/** List files in a section subdirectory, returning paths relative to the directory. */
+export async function listFiles(dir: string, subPath: string = ''): Promise<string[]> {
+  const fullDir = path.join(dir, subPath);
+  const entries = await fs.readdir(fullDir, { withFileTypes: true });
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    const relative = path.join(subPath, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await listFiles(dir, relative);
+      files.push(...nested);
+    } else {
+      files.push(relative);
+    }
+  }
+
+  return files;
+}

package/references/agent-workspace/src/types.ts

@@ -0,0 +1,68 @@
+/**
+ * Minimal schema interface — anything with a `parse` method works (Zod, Joi, custom).
+ * `parse` should throw on invalid data.
+ */
+export interface Schema<T = unknown> {
+  parse(data: unknown): T;
+}
+
+/** Options for creating a workspace. */
+export interface CreateWorkspaceOptions {
+  /** Extra top-level directories to create alongside the defaults. */
+  additionalDirs?: string[];
+}
+
+/** Configuration for WorkspaceManager. */
+export interface WorkspaceManagerConfig {
+  /** Base directory where workspaces are created. Defaults to `os.tmpdir()`. */
+  baseDir?: string;
+  /** Namespace prefix for the workspaces directory. Defaults to `'agent-workspaces'`. */
+  prefix?: string;
+}
+
+/** Metadata persisted alongside a workspace. */
+export interface WorkspaceMeta {
+  id: string;
+  taskType: string;
+  createdAt: string;
+  dirs: string[];
+}
+
+/** Markdown document with optional YAML frontmatter. */
+export interface MarkdownDocument<T = Record<string, unknown>> {
+  frontmatter: T;
+  body: string;
+}
+
+/** Specification for a single expected output file. */
+export interface OutputFileSpec {
+  /** Path relative to the output directory. */
+  path: string;
+  /** Expected file format. */
+  format: 'json' | 'jsonl' | 'markdown' | 'raw';
+  /** Whether the file must exist. */
+  required: boolean;
+  /** Human-readable description (included in error messages). */
+  description?: string;
+  /** Schema for JSON / JSONL validation — must have a `parse` method that throws on invalid data. */
+  schema?: Schema;
+  /** Custom validation function. Throw or return false to indicate failure. */
+  validate?: (content: unknown) => boolean | Promise<boolean>;
+}
+
+/** Full output specification. */
+export interface OutputSpec {
+  files: OutputFileSpec[];
+}
+
+/** A single validation error. */
+export interface ValidationError {
+  path: string;
+  message: string;
+}
+
+/** Result of output validation. */
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+}

package/references/agent-workspace/src/validation.ts

@@ -0,0 +1,93 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { readJson, readJsonl } from './readers/json.js';
+import { readMarkdown } from './readers/markdown.js';
+import { readRaw } from './readers/raw.js';
+import type { OutputFileSpec, OutputSpec, ValidationError, ValidationResult } from './types.js';
+
+/** Validate that expected output files exist and pass schema / custom validation. */
+export async function validateOutput(
+  outputDir: string,
+  spec: OutputSpec,
+): Promise<ValidationResult> {
+  const errors: ValidationError[] = [];
+
+  for (const fileSpec of spec.files) {
+    const fullPath = path.join(outputDir, fileSpec.path);
+
+    // Check existence
+    try {
+      await fs.access(fullPath);
+    } catch {
+      if (fileSpec.required) {
+        const desc = fileSpec.description ? ` (${fileSpec.description})` : '';
+        errors.push({
+          path: fileSpec.path,
+          message: `Required file missing${desc}`,
+        });
+      }
+      continue;
+    }
+
+    // Read and validate content
+    try {
+      const content = await readFileByFormat(outputDir, fileSpec);
+
+      // Schema validation
+      if (fileSpec.schema) {
+        try {
+          if (fileSpec.format === 'jsonl' && Array.isArray(content)) {
+            for (const item of content) {
+              fileSpec.schema.parse(item);
+            }
+          } else {
+            fileSpec.schema.parse(content);
+          }
+        } catch (err) {
+          errors.push({
+            path: fileSpec.path,
+            message: `Schema validation failed: ${err instanceof Error ? err.message : String(err)}`,
+          });
+        }
+      }
+
+      // Custom validate callback
+      if (fileSpec.validate) {
+        try {
+          const result = await fileSpec.validate(content);
+          if (result === false) {
+            errors.push({
+              path: fileSpec.path,
+              message: 'Custom validation returned false',
+            });
+          }
+        } catch (err) {
+          errors.push({
+            path: fileSpec.path,
+            message: `Custom validation threw: ${err instanceof Error ? err.message : String(err)}`,
+          });
+        }
+      }
+    } catch (err) {
+      errors.push({
+        path: fileSpec.path,
+        message: `Failed to read file: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+async function readFileByFormat(outputDir: string, spec: OutputFileSpec): Promise<unknown> {
+  switch (spec.format) {
+    case 'json':
+      return readJson(outputDir, spec.path);
+    case 'jsonl':
+      return readJsonl(outputDir, spec.path);
+    case 'markdown':
+      return readMarkdown(outputDir, spec.path);
+    case 'raw':
+      return readRaw(outputDir, spec.path);
+  }
+}

package/references/agent-workspace/src/writers/json.ts

@@ -0,0 +1,17 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+/** Write a JSON file (pretty-printed). */
+export async function writeJson(dir: string, filePath: string, data: unknown): Promise<void> {
+  const fullPath = path.join(dir, filePath);
+  await fs.mkdir(path.dirname(fullPath), { recursive: true });
+  await fs.writeFile(fullPath, JSON.stringify(data, null, 2) + '\n');
+}
+
+/** Write a JSONL file (one JSON object per line). */
+export async function writeJsonl(dir: string, filePath: string, items: unknown[]): Promise<void> {
+  const fullPath = path.join(dir, filePath);
+  await fs.mkdir(path.dirname(fullPath), { recursive: true });
+  const content = items.map((item) => JSON.stringify(item)).join('\n') + '\n';
+  await fs.writeFile(fullPath, content);
+}

package/references/agent-workspace/src/writers/markdown.ts

@@ -0,0 +1,27 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { stringify as yamlStringify } from 'yaml';
+import type { MarkdownDocument } from '../types.js';
+
+/** Write a markdown file with optional YAML frontmatter. */
+export async function writeMarkdown(
+  dir: string,
+  filePath: string,
+  doc: MarkdownDocument,
+): Promise<void> {
+  const fullPath = path.join(dir, filePath);
+  await fs.mkdir(path.dirname(fullPath), { recursive: true });
+
+  let content = '';
+  if (doc.frontmatter && Object.keys(doc.frontmatter).length > 0) {
+    content += '---\n' + yamlStringify(doc.frontmatter).trimEnd() + '\n---\n\n';
+  }
+  content += doc.body;
+
+  // Ensure trailing newline
+  if (!content.endsWith('\n')) {
+    content += '\n';
+  }
+
+  await fs.writeFile(fullPath, content);
+}

package/references/agent-workspace/src/writers/raw.ts

@@ -0,0 +1,22 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+/** Write raw string content to a file. */
+export async function writeRaw(dir: string, filePath: string, content: string): Promise<void> {
+  const fullPath = path.join(dir, filePath);
+  await fs.mkdir(path.dirname(fullPath), { recursive: true });
+  await fs.writeFile(fullPath, content);
+}
+
+/** Recursively copy a directory into the workspace. */
+export async function copyDir(dir: string, destName: string, srcPath: string): Promise<void> {
+  const fullDest = path.join(dir, destName);
+  await fs.cp(srcPath, fullDest, { recursive: true });
+}
+
+/** Create a symlink inside the workspace pointing to an external path. */
+export async function symlink(dir: string, linkName: string, targetPath: string): Promise<void> {
+  const fullLink = path.join(dir, linkName);
+  await fs.mkdir(path.dirname(fullLink), { recursive: true });
+  await fs.symlink(targetPath, fullLink);
+}