@almadar/agent 2.0.0 → 2.0.1

package/dist/utils/safety/threshold-auth.d.ts

@@ -0,0 +1,70 @@
+/**
+ * ThresholdAuthorizer — K-of-N approval voting for critical agent actions.
+ *
+ * TypeScript port of saezbaldo/ic-agi `ic_agi/threshold_auth.py`.
+ * See: https://github.com/saezbaldo/ic-agi
+ *
+ * TLA+ properties verified in ThresholdAuth.tla:
+ *   P1 ThresholdSafety:       executed => approvals >= K
+ *   P2 NoUnilateralAuthority: K >= 2 enforced in constructor
+ *   P3 DenialFinality:        once denied, resolution immutable
+ *   P4 ResolutionImmutability: resolved => resolution never changes
+ *
+ * Early-denial formula: deny_count > (N - K)
+ * Once enough denials make threshold mathematically unreachable,
+ * the request is immediately resolved as denied.
+ */
+import type { AuditLog } from '../../security/audit-log.js';
+export interface ApprovalRequest {
+    requestId: string;
+    actionDescription: string;
+    criticality: string;
+    requester: string;
+    /** Unix epoch seconds. */
+    createdAt: number;
+    ttlSeconds: number;
+    /** Map of approverId → vote (true = approve, false = deny). */
+    approvals: Map<string, boolean>;
+    resolved: boolean;
+    resolution: 'approved' | 'denied' | 'expired' | null;
+}
+export interface VoteResult {
+    status: 'approved' | 'denied' | 'pending';
+    approvals: number;
+    denials: number;
+    threshold: number;
+    /** Remaining approvals needed to reach threshold. */
+    remaining: number;
+}
+export declare class ThresholdAuthorizer {
+    private requests;
+    private readonly k;
+    private readonly n;
+    private readonly approverIds;
+    private readonly auditLog?;
+    /**
+     * @param k         Minimum approvals required (must be >= 2, P2)
+     * @param approverIds List of registered approver IDs (length >= k)
+     * @param auditLog  Optional audit chain for all voting events
+     */
+    constructor(k: number, approverIds: string[], auditLog?: AuditLog);
+    /**
+     * Create a new approval request for a critical action.
+     * The request window is 5 minutes (300s).
+     */
+    createRequest(actionDescription: string, requester: string, criticality?: string): ApprovalRequest;
+    /**
+     * Submit a vote for a pending request.
+     * Auto-resolves the request when threshold is reached (approve)
+     * or when threshold becomes mathematically unreachable (deny).
+     *
+     * @throws if request not found, already resolved, expired, approver not registered, or double-vote
+     */
+    submitVote(requestId: string, approverId: string, vote: boolean): VoteResult;
+    /** Returns true iff the request is resolved and approved (P1). */
+    isApproved(requestId: string): boolean;
+    /** Returns true iff the request is resolved and denied (P3). */
+    isDenied(requestId: string): boolean;
+    isExpired(requestId: string): boolean;
+    getRequest(requestId: string): ApprovalRequest | undefined;
+}

package/dist/workspace/git-client.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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
+ */
+export interface GitLogEntry {
+    hash: string;
+    message: string;
+    date: string;
+    author: string;
+}
+export interface GitStatus {
+    clean: boolean;
+    staged: string[];
+    modified: string[];
+    untracked: string[];
+}
+export declare class GitClient {
+    private readonly cwd;
+    constructor(cwd: string);
+    /** Get the working directory path. */
+    getCwd(): 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;
+}

package/dist/workspace/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Workspace Module
+ *
+ * Workspace-centric persistence architecture for Almadar agents.
+ * Files in a git-tracked workspace, with pluggable sinks for Firestore, GitHub, etc.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { WorkspaceManager, FirestoreSink } from '@almadar/agent/workspace';
+ *
+ * const workspace = new WorkspaceManager({
+ *   rootDir: '/workspaces/user-123/session-456',
+ *   userId: 'user-123',
+ *   sessionId: 'session-456',
+ *   projectName: 'Taskly',
+ *   sinks: [new FirestoreSink({ userId: 'user-123', saveOrbital: ... })],
+ * });
+ *
+ * await workspace.initialize();          // Create dirs, templates, git init
+ * const memory = await workspace.loadMemory();  // Read .orb instances
+ * // ... agent runs, server calls workspace.onFileWritten() on each write ...
+ * await workspace.endSession();          // Tag, cleanup
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { WorkspaceSink, WorkspaceConfig, FileMeta, SinkResult, MemorySnapshot, } from './types.js';
+export { WORKSPACE_LAYOUT } from './types.js';
+export { WorkspaceManager } from './workspace-manager.js';
+export { SinkManager } from './sink-manager.js';
+export { GitClient } from './git-client.js';
+export type { GitLogEntry, GitStatus } from './git-client.js';
+export { GitSink } from './sinks/git-sink.js';
+export { FirestoreSink } from './sinks/firestore-sink.js';
+export type { FirestoreSinkConfig } from './sinks/firestore-sink.js';
+export { createUserOrbTemplate, createProjectOrbTemplate, createSchemaOrbTemplate, serializeOrb, parseOrb, } from './templates.js';
+export { readOrbInstances, readOrb, writeOrbInstances, writeOrb, } from './memory-files.js';

package/dist/workspace/memory-files.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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
+ */
+import type { OrbitalSchema } from '@almadar/core';
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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).
+ */
+export declare function writeOrbInstances(filePath: string, instances: Record<string, unknown>[]): Promise<boolean>;
+/**
+ * Write a complete OrbitalSchema to an .orb file.
+ */
+export declare function writeOrb(filePath: string, schema: OrbitalSchema): Promise<void>;

package/dist/workspace/sink-manager.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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
+ */
+import type { WorkspaceSink, FileMeta, SinkResult } from './types.js';
+export 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[]>;
+}

package/dist/workspace/sinks/firestore-sink.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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
+ */
+import type { WorkspaceSink, FileMeta } from '../types.js';
+/**
+ * Injected dependencies for FirestoreSink.
+ * The server provides these — the agent package has no Firestore dependency.
+ */
+export 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;
+}
+export 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>;
+}

package/dist/workspace/sinks/git-sink.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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).
+ *
+ * Optionally pushes to a remote GitHub repo on session end via `enablePush()`.
+ * Push failures are non-fatal (logged, local commits preserved).
+ *
+ * Gracefully degrades if git is not available (logs warning, no-ops).
+ *
+ * @packageDocumentation
+ */
+import type { WorkspaceSink, FileMeta } from '../types.js';
+/**
+ * Configuration for pushing to a remote GitHub repository on session end.
+ */
+export interface GitSinkPushConfig {
+    token: string;
+    branch: string;
+    repoUrl: string;
+}
+export declare class GitSink implements WorkspaceSink {
+    readonly name = "git";
+    private readonly client;
+    private commitQueue;
+    private available;
+    private pushConfig;
+    constructor(workspaceRoot: string);
+    /** Initialize the git repo. Must be called before onFileWritten. */
+    initialize(): Promise<void>;
+    /**
+     * Enable pushing to a remote GitHub repo on session end.
+     * Push failures are non-fatal — local commits are always preserved.
+     */
+    enablePush(config: GitSinkPushConfig): void;
+    /** Get the working directory path. */
+    getCwd(): string;
+    onFileWritten(path: string, _content: string, meta: FileMeta): Promise<void>;
+    onSessionEnd(sessionId: string): Promise<void>;
+    /**
+     * Push local commits to the remote GitHub repository.
+     * Non-fatal — failures are logged but do not throw.
+     */
+    private pushToRemote;
+}

package/dist/workspace/sinks/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Workspace Sinks
+ *
+ * Pluggable persistence backends for workspace file writes.
+ */
+export { GitSink } from './git-sink.js';
+export type { GitSinkPushConfig } from './git-sink.js';
+export { FirestoreSink } from './firestore-sink.js';
+export type { FirestoreSinkConfig } from './firestore-sink.js';

package/dist/workspace/templates.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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
+ */
+import type { OrbitalSchema } from '@almadar/core';
+/**
+ * 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.
+ */
+export declare function createUserOrbTemplate(userId: string): OrbitalSchema;
+/**
+ * Create the project.orb template — tracks project domain knowledge.
+ *
+ * Accumulates known entities, relations, and domain terms across sessions.
+ */
+export declare function createProjectOrbTemplate(projectName: string, appId?: string): OrbitalSchema;
+/**
+ * Create the schema.orb template — empty scaffold for a new generation.
+ */
+export declare function createSchemaOrbTemplate(name: string): OrbitalSchema;
+/** Serialize an OrbitalSchema to a formatted JSON string. */
+export declare function serializeOrb(schema: OrbitalSchema): string;
+/** Parse a JSON string into an OrbitalSchema. Returns null on parse failure. */
+export declare function parseOrb(content: string): OrbitalSchema | null;

package/dist/workspace/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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. */
+export 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. */
+export 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.
+ */
+export 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. */
+export 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. */
+export 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. */
+export interface MemorySnapshot {
+    /** User preferences from .almadar/user.orb instances. */
+    user: Record<string, unknown>[];
+    /** Project context from .almadar/project.orb instances. */
+    project: Record<string, unknown>[];
+}

package/dist/workspace/workspace-manager.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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
+ */
+import type { WorkspaceConfig, FileMeta, SinkResult, MemorySnapshot } from './types.js';
+import { SinkManager } from './sink-manager.js';
+export 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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/agent",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "AI agent infrastructure for Almadar orbital schema generation",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,10 +44,10 @@
   },
   "dependencies": {
     "@almadar/core": ">=2.0.0",
-    "@almadar/integrations": ">=2.0.0",
-    "@almadar/llm": ">=2.0.0",
+    "@almadar/integrations": ">=2.0.1",
+    "@almadar/llm": ">=2.0.1",
     "@almadar/patterns": ">=2.0.0",
-    "@almadar/skills": ">=2.0.0",
+    "@almadar/skills": ">=2.0.1",
     "uuid": "^9.0.0",
     "zod": "^3.22.0"
   },
@@ -82,7 +82,8 @@
     "deepagents": "^1.7.3",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "@types/node": "^22.0.0"
   },
   "repository": {
     "type": "git",
@@ -99,7 +100,7 @@
   ],
   "homepage": "https://github.com/almadar-io/almadar#readme",
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc --declaration --emitDeclarationOnly --outDir dist --rootDir src --skipLibCheck || true",
     "build:watch": "tsup --watch",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",