@almadar/agent 1.6.4 → 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

@@ -1,355 +1,38 @@
-import { OrbitalSchema } from '@almadar/core';
-
 /**
- * Workspace Types
+ * Workspace Module
  *
- * 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.
+ * Workspace-centric persistence architecture for Almadar agents.
+ * Files in a git-tracked workspace, 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.
+ * ## Quick Start
  *
- * Key property: each orbital is its own Firestore document.
- * Two subagents writing different orbitals = zero contention.
+ * ```typescript
+ * import { WorkspaceManager, FirestoreSink } from '@almadar/agent/workspace';
  *
- * @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.
+ * 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: ... })],
+ * });
  *
- * 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.
+ * 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
  */
-
-/**
- * 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 };
+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/index.js

@@ -68,6 +68,10 @@ var GitClient = class {
   constructor(cwd) {
     this.cwd = cwd;
   }
+  /** Get the working directory path. */
+  getCwd() {
+    return this.cwd;
+  }
   /** Check if git is available on the system. */
   static async isAvailable() {
     try {
@@ -198,6 +202,7 @@ var GitSink = class {
     this.name = "git";
     this.commitQueue = Promise.resolve();
     this.available = null;
+    this.pushConfig = null;
     this.client = new GitClient(workspaceRoot);
   }
   /** Initialize the git repo. Must be called before onFileWritten. */
@@ -209,6 +214,17 @@ var GitSink = class {
     }
     await this.client.init();
   }
+  /**
+   * Enable pushing to a remote GitHub repo on session end.
+   * Push failures are non-fatal — local commits are always preserved.
+   */
+  enablePush(config) {
+    this.pushConfig = config;
+  }
+  /** Get the working directory path. */
+  getCwd() {
+    return this.client.getCwd();
+  }
   async onFileWritten(path, _content, meta) {
     if (!this.available) return;
     this.commitQueue = this.commitQueue.then(async () => {
@@ -230,6 +246,29 @@ var GitSink = class {
       `session/${sessionId}`,
       `Session ${sessionId} complete`
     );
+    if (this.pushConfig) {
+      await this.pushToRemote();
+    }
+  }
+  /**
+   * Push local commits to the remote GitHub repository.
+   * Non-fatal — failures are logged but do not throw.
+   */
+  async pushToRemote() {
+    if (!this.pushConfig) return;
+    const { token, branch, repoUrl } = this.pushConfig;
+    const cwd = this.client.getCwd();
+    try {
+      console.log(`[GitSink] Pushing to ${repoUrl} branch ${branch}...`);
+      const { push } = await import('@almadar/integrations/github');
+      await push({ branchName: branch, workDir: cwd }, cwd, token);
+      console.log(`[GitSink] Push successful`);
+    } catch (error) {
+      console.error(
+        `[GitSink] Push failed (local commits preserved):`,
+        error instanceof Error ? error.message : error
+      );
+    }
   }
 };
 function formatCommitMessage(path, meta) {