@almadar/agent 1.6.1 → 1.6.2

package/dist/workspace/index.d.ts

@@ -0,0 +1,355 @@
+import { OrbitalSchema } from '@almadar/core';
+
+/**
+ * Workspace Types
+ *
+ * Core type definitions for the workspace-centric persistence architecture.
+ * The workspace is the central unit: files in a git-tracked directory,
+ * with pluggable sinks for Firestore, GitHub, etc.
+ *
+ * @packageDocumentation
+ */
+/** Standard directory structure inside a workspace. */
+declare const WORKSPACE_LAYOUT: {
+    /** Root directory for Almadar workspace state. */
+    readonly ALMADAR_DIR: ".almadar";
+    /** User preferences and learned patterns. */
+    readonly USER_MEMORY: ".almadar/user.orb";
+    /** Project-level domain knowledge. */
+    readonly PROJECT_MEMORY: ".almadar/project.orb";
+    /** The generation artifact (shared memory for all agents). */
+    readonly SCHEMA: ".almadar/schema.orb";
+    /** Individual orbital files (one per subagent). */
+    readonly ORBITALS_DIR: ".almadar/orbitals";
+};
+/** Classification of a file write for routing to appropriate sinks. */
+interface FileMeta {
+    /** What kind of file was written. */
+    fileType: 'schema' | 'orbital' | 'memory' | 'domain' | 'other';
+    /** Orbital name (only when fileType is 'orbital'). */
+    orbitalName?: string;
+    /** Session ID for attribution. */
+    sessionId?: string;
+}
+/**
+ * A pluggable persistence backend that reacts to workspace file writes.
+ *
+ * Sinks are registered with the SinkManager and notified on every file write.
+ * Each sink is independent — a failure in one does not affect others.
+ */
+interface WorkspaceSink {
+    /** Human-readable name for logging/diagnostics. */
+    readonly name: string;
+    /**
+     * Called when a file is written to the workspace.
+     * @param path - Relative path within the workspace root
+     * @param content - File content as a string
+     * @param meta - Classification metadata for routing
+     */
+    onFileWritten(path: string, content: string, meta: FileMeta): Promise<void>;
+    /**
+     * Called when the session ends. Used for cleanup, final sync, tagging, etc.
+     * @param sessionId - The session being ended
+     */
+    onSessionEnd(sessionId: string): Promise<void>;
+}
+/** Result of notifying a single sink. */
+interface SinkResult {
+    /** Which sink produced this result. */
+    sinkName: string;
+    /** Whether the sink operation succeeded. */
+    success: boolean;
+    /** Error details if the operation failed. */
+    error?: Error;
+}
+/** Configuration for initializing a workspace. */
+interface WorkspaceConfig {
+    /** Absolute path to the workspace root directory. */
+    rootDir: string;
+    /** User ID for memory file attribution. */
+    userId: string;
+    /** Session ID for git tags and logging. */
+    sessionId: string;
+    /** App ID (may be assigned later on first schema write). */
+    appId?: string;
+    /** Project name for the schema template. */
+    projectName?: string;
+    /** Whether to initialize git in the workspace. Defaults to true. */
+    gitEnabled?: boolean;
+    /** Sinks to register on initialization. */
+    sinks?: WorkspaceSink[];
+}
+/** Snapshot of all .orb memory file instances, read at session start. */
+interface MemorySnapshot {
+    /** User preferences from .almadar/user.orb instances. */
+    user: Record<string, unknown>[];
+    /** Project context from .almadar/project.orb instances. */
+    project: Record<string, unknown>[];
+}
+
+/**
+ * SinkManager — Fan-out file writes to registered workspace sinks.
+ *
+ * Uses Promise.allSettled for fault isolation: a Firestore error
+ * does not prevent the git commit, and vice versa.
+ *
+ * @packageDocumentation
+ */
+
+declare class SinkManager {
+    private readonly sinks;
+    /** Register a sink to receive file write notifications. */
+    register(sink: WorkspaceSink): void;
+    /** Get registered sink names (for diagnostics). */
+    get registeredSinks(): string[];
+    /**
+     * Notify all sinks that a file was written.
+     * Returns results from each sink — failures in one don't affect others.
+     */
+    notifyFileWritten(path: string, content: string, meta: FileMeta): Promise<SinkResult[]>;
+    /**
+     * Notify all sinks that the session has ended.
+     * Returns results from each sink — failures in one don't affect others.
+     */
+    notifySessionEnd(sessionId: string): Promise<SinkResult[]>;
+}
+
+/**
+ * WorkspaceManager — Lifecycle management for agent workspaces.
+ *
+ * Handles initialization (create dirs, write .orb templates, git init),
+ * file write notifications (fan out to sinks), memory read/write,
+ * and session end (final commit, tag, cleanup).
+ *
+ * @packageDocumentation
+ */
+
+declare class WorkspaceManager {
+    private readonly config;
+    private readonly sinkManager;
+    private gitSink;
+    private initialized;
+    constructor(config: WorkspaceConfig);
+    /** Get the absolute path to a workspace-relative path. */
+    resolve(relativePath: string): string;
+    /** Get the SinkManager for direct registration of additional sinks. */
+    get sinks(): SinkManager;
+    /**
+     * Initialize the workspace: create directories, write .orb templates,
+     * optionally initialize git.
+     *
+     * Safe to call multiple times — skips if already initialized.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Notify sinks that a file was written.
+     * Call this from the server when the agent writes a file.
+     *
+     * @param relativePath - Path relative to workspace root
+     * @param content - File content as string
+     * @param meta - Optional metadata override (auto-inferred if not provided)
+     */
+    onFileWritten(relativePath: string, content: string, meta?: Partial<FileMeta>): Promise<SinkResult[]>;
+    /**
+     * Load memory from .orb files. Call at session start to provide
+     * the agent with user preferences and project context.
+     */
+    loadMemory(): Promise<MemorySnapshot>;
+    /**
+     * Update memory .orb file instances. Call at session end to
+     * persist learned preferences and discovered domain knowledge.
+     */
+    saveMemory(updates: {
+        user?: Record<string, unknown>[];
+        project?: Record<string, unknown>[];
+    }): Promise<void>;
+    /**
+     * End the session: notify all sinks, create git tag.
+     * Call from the server when the agent session completes.
+     */
+    endSession(): Promise<SinkResult[]>;
+    private writeTemplateIfMissing;
+}
+
+/**
+ * GitClient — Thin wrapper around local git CLI operations.
+ *
+ * Uses child_process.execFile for safety (no shell injection).
+ * Designed for workspace-local operations only (init, add, commit, tag).
+ * Remote operations (push, PR) use @almadar/integrations instead.
+ *
+ * @packageDocumentation
+ */
+interface GitLogEntry {
+    hash: string;
+    message: string;
+    date: string;
+    author: string;
+}
+interface GitStatus {
+    clean: boolean;
+    staged: string[];
+    modified: string[];
+    untracked: string[];
+}
+declare class GitClient {
+    private readonly cwd;
+    constructor(cwd: string);
+    /** Check if git is available on the system. */
+    static isAvailable(): Promise<boolean>;
+    /** Check if the workspace is already a git repository. */
+    isRepo(): Promise<boolean>;
+    /** Initialize a new git repository. No-op if already initialized. */
+    init(): Promise<void>;
+    /** Stage files for commit. */
+    add(paths: string[]): Promise<void>;
+    /** Stage all changes (equivalent to git add -A). */
+    addAll(): Promise<void>;
+    /**
+     * Create a commit with the given message.
+     * Returns the commit hash, or null if there was nothing to commit.
+     */
+    commit(message: string): Promise<string | null>;
+    /** Create an annotated tag. */
+    tag(name: string, message?: string): Promise<void>;
+    /** Get recent commits. */
+    log(limit?: number): Promise<GitLogEntry[]>;
+    /** Get workspace status. */
+    status(): Promise<GitStatus>;
+    /** Get diff output between two references. */
+    diff(from?: string, to?: string): Promise<string>;
+    private exec;
+}
+
+/**
+ * GitSink — Auto-commit workspace file writes to a local git repository.
+ *
+ * Implements the WorkspaceSink interface. Every file write becomes a git commit
+ * with a structured message. Concurrent writes are serialized via a commit queue
+ * to prevent git lock contention (handles parallel subagent case).
+ *
+ * Gracefully degrades if git is not available (logs warning, no-ops).
+ *
+ * @packageDocumentation
+ */
+
+declare class GitSink implements WorkspaceSink {
+    readonly name = "git";
+    private readonly client;
+    private commitQueue;
+    private available;
+    constructor(workspaceRoot: string);
+    /** Initialize the git repo. Must be called before onFileWritten. */
+    initialize(): Promise<void>;
+    onFileWritten(path: string, _content: string, meta: FileMeta): Promise<void>;
+    onSessionEnd(sessionId: string): Promise<void>;
+}
+
+/**
+ * FirestoreSink — Per-orbital Firestore persistence as a workspace sink.
+ *
+ * Takes injected save functions so @almadar/agent stays free of firebase-admin.
+ * The server provides concrete implementations via KFlowAccessLayer.
+ *
+ * Key property: each orbital is its own Firestore document.
+ * Two subagents writing different orbitals = zero contention.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Injected dependencies for FirestoreSink.
+ * The server provides these — the agent package has no Firestore dependency.
+ */
+interface FirestoreSinkConfig {
+    /** User ID for Firestore document paths. */
+    userId: string;
+    /** App ID (may be assigned later on first schema write). */
+    appId?: string;
+    /** Save a single orbital to its own Firestore document. */
+    saveOrbital(orbitalName: string, orbital: unknown): Promise<void>;
+    /** Save schema metadata (name, version, config). */
+    saveSchema?(schema: unknown): Promise<{
+        appId: string;
+    }>;
+    /** Save memory updates (user preferences, project context). */
+    saveMemory?(memoryType: string, data: unknown): Promise<void>;
+    /** Callback when a new app is created (for SSE event emission). */
+    onAppCreated?(appId: string): void;
+}
+declare class FirestoreSink implements WorkspaceSink {
+    readonly name = "firestore";
+    private readonly config;
+    constructor(config: FirestoreSinkConfig);
+    /** Update the appId after it's been assigned (e.g., on first schema write). */
+    setAppId(appId: string): void;
+    onFileWritten(_path: string, content: string, meta: FileMeta): Promise<void>;
+    onSessionEnd(_sessionId: string): Promise<void>;
+}
+
+/**
+ * Workspace Templates
+ *
+ * .orb memory file templates as TypeScript constants.
+ * These are written to `.almadar/` on workspace initialization.
+ *
+ * Reuses entity definitions from `memory-orbital.ts` for type consistency.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Create the user.orb template — tracks user preferences with a temporal learning trait.
+ *
+ * The `instances` field carries the living memory data.
+ * Git commits to this file ARE the state transitions over time.
+ */
+declare function createUserOrbTemplate(userId: string): OrbitalSchema;
+/**
+ * Create the project.orb template — tracks project domain knowledge.
+ *
+ * Accumulates known entities, relations, and domain terms across sessions.
+ */
+declare function createProjectOrbTemplate(projectName: string, appId?: string): OrbitalSchema;
+/**
+ * Create the schema.orb template — empty scaffold for a new generation.
+ */
+declare function createSchemaOrbTemplate(name: string): OrbitalSchema;
+/** Serialize an OrbitalSchema to a formatted JSON string. */
+declare function serializeOrb(schema: OrbitalSchema): string;
+/** Parse a JSON string into an OrbitalSchema. Returns null on parse failure. */
+declare function parseOrb(content: string): OrbitalSchema | null;
+
+/**
+ * Memory Files — Read/write .orb memory file instances.
+ *
+ * The `instances` field on an OrbitalSchema entity is the living data carrier.
+ * These utilities read and write that field without touching the rest of the schema.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Read the `instances` array from the first orbital's entity in an .orb file.
+ * Returns an empty array if the file doesn't exist or has no instances.
+ */
+declare function readOrbInstances(filePath: string): Promise<Record<string, unknown>[]>;
+/**
+ * Read and parse a complete .orb file.
+ * Returns null if the file doesn't exist or is invalid JSON.
+ */
+declare function readOrb(filePath: string): Promise<OrbitalSchema | null>;
+/**
+ * Update the `instances` array in the first orbital's entity of an .orb file.
+ * Preserves the rest of the schema structure (traits, pages, etc.).
+ *
+ * If the file doesn't exist, this is a no-op (the workspace should be
+ * initialized with templates first).
+ */
+declare function writeOrbInstances(filePath: string, instances: Record<string, unknown>[]): Promise<boolean>;
+/**
+ * Write a complete OrbitalSchema to an .orb file.
+ */
+declare function writeOrb(filePath: string, schema: OrbitalSchema): Promise<void>;
+
+export { type FileMeta, FirestoreSink, type FirestoreSinkConfig, GitClient, type GitLogEntry, GitSink, type GitStatus, type MemorySnapshot, SinkManager, type SinkResult, WORKSPACE_LAYOUT, type WorkspaceConfig, WorkspaceManager, type WorkspaceSink, createProjectOrbTemplate, createSchemaOrbTemplate, createUserOrbTemplate, parseOrb, readOrb, readOrbInstances, serializeOrb, writeOrb, writeOrbInstances };