@inf-minds/jobs 0.0.1

package/src/artifact-manager.ts

@@ -0,0 +1,346 @@
+// ABOUTME: ArtifactManager for job artifact CRUD operations
+// ABOUTME: Routes artifacts to appropriate storage backend
+
+import type { StorageProvider } from '@inf-minds/storage';
+import { detectMimeType, getStorageType } from '@inf-minds/storage';
+import type { ArtifactRef, ArtifactContent, SaveArtifactOptions } from './types.js';
+import { jobArtifacts, type JobArtifact, type NewJobArtifact } from './schema.js';
+import { and, eq, sql } from 'drizzle-orm';
+
+export interface ArtifactManagerDb {
+  insert(table: unknown): {
+    values(record: unknown): {
+      returning(): Promise<unknown[]>;
+    };
+  };
+  select(): {
+    from(table: unknown): {
+      where(condition: unknown): Promise<unknown[]>;
+    };
+  };
+  delete(table: unknown): {
+    where(condition: unknown): Promise<unknown>;
+  };
+}
+
+export interface ArtifactManagerOptions {
+  db: ArtifactManagerDb;
+  postgresStorage: StorageProvider;
+  externalStorage: StorageProvider;
+  table?: unknown;
+}
+
+export interface ArtifactManager {
+  save(jobId: string, name: string, content: string | Buffer, options: SaveArtifactOptions): Promise<ArtifactRef>;
+  load(jobId: string, name: string): Promise<ArtifactContent | null>;
+  list(jobId: string): Promise<ArtifactRef[]>;
+  getSignedUrl(jobId: string, name: string, expiresIn?: number): Promise<string | null>;
+  delete(jobId: string, name: string): Promise<void>;
+  deleteAll(jobId: string): Promise<void>;
+
+  // Session/visibility queries for kernel orchestration
+  /** List all artifacts for a kernel session */
+  listBySession(sessionId: string): Promise<ArtifactRef[]>;
+  /** List artifacts for a specific node in a session */
+  listByNode(sessionId: string, nodeId: string): Promise<ArtifactRef[]>;
+  /** List artifacts by visibility scope in a session */
+  listByVisibility(sessionId: string, visibility: string): Promise<ArtifactRef[]>;
+  /** List artifacts published to specific channels in a session */
+  listByChannels(sessionId: string, channels: string[]): Promise<ArtifactRef[]>;
+}
+
+export function createArtifactManager(options: ArtifactManagerOptions): ArtifactManager {
+  const { db, postgresStorage, externalStorage } = options;
+  const table = options.table ?? jobArtifacts;
+
+  return {
+    async save(jobId: string, name: string, content: string | Buffer, options: SaveArtifactOptions): Promise<ArtifactRef> {
+      // Determine MIME type
+      const mimeType = options.mimeType ?? detectMimeType(name);
+
+      // Determine storage type based on MIME type
+      const storageType = getStorageType(mimeType);
+
+      // Select appropriate storage backend
+      const storage = storageType === 'postgres' ? postgresStorage : externalStorage;
+
+      // Build storage key
+      const storageKey = storageType === 'postgres' ? name : `${jobId}/${name}`;
+
+      // Store content in appropriate backend
+      const putResult = await storage.put(storageKey, content, {
+        mimeType,
+        metadata: options.metadata,
+      });
+
+      // Calculate expiry timestamp
+      let expiresAt: Date | null = null;
+      if (options.expiresIn) {
+        expiresAt = new Date(Date.now() + options.expiresIn * 1000);
+      }
+
+      // Build artifact record
+      const artifactRecord: NewJobArtifact = {
+        jobId,
+        name,
+        mimeType,
+        storageType,
+        content: storageType === 'postgres' ? (typeof content === 'string' ? { text: content } : content) : null,
+        externalKey: storageType === 'external' ? putResult.key : null,
+        sizeBytes: putResult.sizeBytes,
+        metadata: options.metadata ?? {},
+        expiresAt,
+      };
+
+      // Insert into database
+      const [inserted] = await db
+        .insert(table)
+        .values(artifactRecord)
+        .returning();
+
+      if (!inserted) {
+        throw new Error('Failed to insert artifact record');
+      }
+
+      const artifact = inserted as JobArtifact;
+
+      // Return artifact reference
+      return {
+        name: artifact.name,
+        mimeType: artifact.mimeType,
+        sizeBytes: artifact.sizeBytes,
+        storageType: artifact.storageType as 'postgres' | 'external',
+        metadata: (artifact.metadata as Record<string, unknown>) ?? {},
+        createdAt: artifact.createdAt,
+      };
+    },
+
+    async load(jobId: string, name: string): Promise<ArtifactContent | null> {
+      // Query database for artifact record
+      const results = await db
+        .select()
+        .from(table)
+        .where(and(eq(jobArtifacts.jobId, jobId), eq(jobArtifacts.name, name)));
+
+      if (results.length === 0) {
+        return null;
+      }
+
+      const artifact = results[0] as JobArtifact;
+
+      // Fetch content from appropriate storage
+      let content: string | Buffer;
+
+      if (artifact.storageType === 'postgres') {
+        const storageResult = await postgresStorage.get(artifact.name);
+        if (!storageResult) {
+          throw new Error(`Artifact content not found in postgres storage: ${artifact.name}`);
+        }
+        content = storageResult.content;
+      } else {
+        if (!artifact.externalKey) {
+          throw new Error(`External key missing for artifact: ${artifact.name}`);
+        }
+        const storageResult = await externalStorage.get(artifact.externalKey);
+        if (!storageResult) {
+          throw new Error(`Artifact content not found in external storage: ${artifact.externalKey}`);
+        }
+        content = storageResult.content;
+      }
+
+      // Return artifact with content
+      return {
+        name: artifact.name,
+        mimeType: artifact.mimeType,
+        sizeBytes: artifact.sizeBytes,
+        storageType: artifact.storageType as 'postgres' | 'external',
+        metadata: (artifact.metadata as Record<string, unknown>) ?? {},
+        createdAt: artifact.createdAt,
+        content,
+      };
+    },
+
+    async list(jobId: string): Promise<ArtifactRef[]> {
+      // Query database for all artifacts for this job
+      const results = await db
+        .select()
+        .from(table)
+        .where(eq(jobArtifacts.jobId, jobId));
+
+      // Map to artifact references
+      return results.map((artifact) => {
+        const a = artifact as JobArtifact;
+        return {
+          name: a.name,
+          mimeType: a.mimeType,
+          sizeBytes: a.sizeBytes,
+          storageType: a.storageType as 'postgres' | 'external',
+          metadata: (a.metadata as Record<string, unknown>) ?? {},
+          createdAt: a.createdAt,
+        };
+      });
+    },
+
+    async getSignedUrl(jobId: string, name: string, expiresIn?: number): Promise<string | null> {
+      // Query database for artifact record
+      const results = await db
+        .select()
+        .from(table)
+        .where(and(eq(jobArtifacts.jobId, jobId), eq(jobArtifacts.name, name)));
+
+      if (results.length === 0) {
+        return null;
+      }
+
+      const artifact = results[0] as JobArtifact;
+
+      // Only external artifacts can have signed URLs
+      if (artifact.storageType !== 'external' || !artifact.externalKey) {
+        return null;
+      }
+
+      // Get signed URL from external storage
+      return await externalStorage.getSignedUrl(artifact.externalKey, expiresIn);
+    },
+
+    async delete(jobId: string, name: string): Promise<void> {
+      // Query database for artifact record
+      const results = await db
+        .select()
+        .from(table)
+        .where(and(eq(jobArtifacts.jobId, jobId), eq(jobArtifacts.name, name)));
+
+      if (results.length === 0) {
+        return;
+      }
+
+      const artifact = results[0] as JobArtifact;
+
+      // Delete from appropriate storage
+      if (artifact.storageType === 'postgres') {
+        await postgresStorage.delete(artifact.name);
+      } else if (artifact.externalKey) {
+        await externalStorage.delete(artifact.externalKey);
+      }
+
+      // Delete database record
+      await db
+        .delete(table)
+        .where(and(eq(jobArtifacts.jobId, jobId), eq(jobArtifacts.name, name)));
+    },
+
+    async deleteAll(jobId: string): Promise<void> {
+      // Get all artifacts for this job
+      const artifacts = await db
+        .select()
+        .from(table)
+        .where(eq(jobArtifacts.jobId, jobId));
+
+      // Delete from storage backends
+      for (const artifact of artifacts) {
+        const a = artifact as JobArtifact;
+        if (a.storageType === 'postgres') {
+          await postgresStorage.delete(a.name);
+        } else if (a.externalKey) {
+          await externalStorage.delete(a.externalKey);
+        }
+      }
+
+      // Delete all database records
+      await db
+        .delete(table)
+        .where(eq(jobArtifacts.jobId, jobId));
+    },
+
+    // Session/visibility query implementations
+
+    async listBySession(sessionId: string): Promise<ArtifactRef[]> {
+      const results = await db
+        .select()
+        .from(table)
+        .where(eq(jobArtifacts.sessionId, sessionId));
+
+      return results.map((artifact) => {
+        const a = artifact as JobArtifact;
+        return {
+          name: a.name,
+          mimeType: a.mimeType,
+          sizeBytes: a.sizeBytes,
+          storageType: a.storageType as 'postgres' | 'external',
+          metadata: (a.metadata as Record<string, unknown>) ?? {},
+          createdAt: a.createdAt,
+        };
+      });
+    },
+
+    async listByNode(sessionId: string, nodeId: string): Promise<ArtifactRef[]> {
+      const results = await db
+        .select()
+        .from(table)
+        .where(and(eq(jobArtifacts.sessionId, sessionId), eq(jobArtifacts.nodeId, nodeId)));
+
+      return results.map((artifact) => {
+        const a = artifact as JobArtifact;
+        return {
+          name: a.name,
+          mimeType: a.mimeType,
+          sizeBytes: a.sizeBytes,
+          storageType: a.storageType as 'postgres' | 'external',
+          metadata: (a.metadata as Record<string, unknown>) ?? {},
+          createdAt: a.createdAt,
+        };
+      });
+    },
+
+    async listByVisibility(sessionId: string, visibility: string): Promise<ArtifactRef[]> {
+      const results = await db
+        .select()
+        .from(table)
+        .where(and(eq(jobArtifacts.sessionId, sessionId), eq(jobArtifacts.visibility, visibility)));
+
+      return results.map((artifact) => {
+        const a = artifact as JobArtifact;
+        return {
+          name: a.name,
+          mimeType: a.mimeType,
+          sizeBytes: a.sizeBytes,
+          storageType: a.storageType as 'postgres' | 'external',
+          metadata: (a.metadata as Record<string, unknown>) ?? {},
+          createdAt: a.createdAt,
+        };
+      });
+    },
+
+    async listByChannels(sessionId: string, channels: string[]): Promise<ArtifactRef[]> {
+      if (channels.length === 0) {
+        return [];
+      }
+
+      // Query for artifacts where channels array overlaps with requested channels
+      const results = await db
+        .select()
+        .from(table)
+        .where(
+          and(
+            eq(jobArtifacts.sessionId, sessionId),
+            sql`${jobArtifacts.channels} && ARRAY[${sql.join(
+              channels.map((c) => sql`${c}`),
+              sql`, `
+            )}]::text[]`
+          )
+        );
+
+      return results.map((artifact) => {
+        const a = artifact as JobArtifact;
+        return {
+          name: a.name,
+          mimeType: a.mimeType,
+          sizeBytes: a.sizeBytes,
+          storageType: a.storageType as 'postgres' | 'external',
+          metadata: (a.metadata as Record<string, unknown>) ?? {},
+          createdAt: a.createdAt,
+        };
+      });
+    },
+  };
+}

package/src/artifact-materializer.ts

@@ -0,0 +1,64 @@
+// ABOUTME: Materializes artifacts from job dependencies
+// ABOUTME: Makes parent job artifacts available via deps/{jobId}/{name} paths
+
+import type { ArtifactManager } from './artifact-manager.js';
+import type { ArtifactContent } from './types.js';
+import type { MaterializedArtifacts } from './job-context.js';
+
+export interface ArtifactMaterializerDb {
+  select(): {
+    from(table: unknown): {
+      where(condition: unknown): Promise<{ dependsOnJobId: string }[]>;
+    };
+  };
+}
+
+export interface ArtifactMaterializerOptions {
+  db: ArtifactMaterializerDb;
+  artifactManager: Pick<ArtifactManager, 'list' | 'load'>;
+  dependenciesTable?: unknown;
+}
+
+export interface ArtifactMaterializer {
+  materialize(jobId: string): Promise<MaterializedArtifacts>;
+}
+
+export function createArtifactMaterializer(
+  options: ArtifactMaterializerOptions
+): ArtifactMaterializer {
+  const { db, artifactManager } = options;
+
+  return {
+    async materialize(jobId: string): Promise<MaterializedArtifacts> {
+      const artifacts = new Map<string, ArtifactContent>();
+
+      // Get job dependencies
+      const dependencies = await (db.select as any)()
+        .from(null)
+        .where({ jobId });
+
+      if (dependencies.length === 0) {
+        return { artifacts };
+      }
+
+      // Load artifacts from each dependency
+      for (const dep of dependencies) {
+        const parentJobId = dep.dependsOnJobId;
+
+        // List artifacts for parent job
+        const parentArtifacts = await artifactManager.list(parentJobId);
+
+        // Load each artifact
+        for (const ref of parentArtifacts) {
+          const content = await artifactManager.load(parentJobId, ref.name);
+          if (content) {
+            const path = `deps/${parentJobId}/${ref.name}`;
+            artifacts.set(path, content);
+          }
+        }
+      }
+
+      return { artifacts };
+    },
+  };
+}

package/src/artifact-router.ts

@@ -0,0 +1,151 @@
+// ABOUTME: ArtifactRouter interface for kernel artifact visibility and routing
+// ABOUTME: Determines which artifacts nodes can access and how outputs are routed
+
+import type { ArtifactRef, GraphState } from './types.js';
+import type { ArtifactVisibility } from './schema.js';
+
+/**
+ * Graph edge definition (simplified for routing context).
+ */
+export interface GraphEdge {
+  /** Source node ID */
+  source: string;
+  /** Target node ID */
+  target: string;
+  /** Named channel for artifact routing (optional) */
+  channel?: string;
+}
+
+/**
+ * Context provided for artifact routing decisions.
+ */
+export interface RoutingContext {
+  /** Kernel session ID (the parent job ID) */
+  sessionId: string;
+  /** Current node ID in the graph */
+  nodeId: string;
+  /** Mind ID being executed (e.g., 'researcher', 'coordinator') */
+  mindId: string;
+  /** The incoming edge that triggered this node (optional for start nodes) */
+  edge?: GraphEdge;
+  /** Current graph execution state */
+  graphState: GraphState;
+  /** Account ID for the session */
+  accountId: string;
+}
+
+/**
+ * Hints provided by minds when saving artifacts.
+ */
+export interface VisibilityHints {
+  /** Explicit visibility scope override */
+  scope?: ArtifactVisibility;
+  /** Specific recipient node IDs */
+  recipients?: string[];
+  /** Named channels to publish to */
+  channels?: string[];
+  /** Whether this artifact should persist beyond session */
+  persistent?: boolean;
+}
+
+/**
+ * Artifact with routing metadata.
+ */
+export interface RoutedArtifact extends ArtifactRef {
+  /** Resolved visibility scope */
+  visibility: ArtifactVisibility;
+  /** Session this artifact belongs to */
+  sessionId: string;
+  /** Node that created this artifact */
+  nodeId: string;
+  /** Channels this artifact is published to */
+  channels: string[];
+}
+
+/**
+ * Options for resolving input artifacts.
+ */
+export interface ResolveInputOptions {
+  /** Filter by visibility scopes */
+  visibilities?: ArtifactVisibility[];
+  /** Filter by specific channels */
+  channels?: string[];
+  /** Filter by source node IDs */
+  sourceNodes?: string[];
+  /** Include artifacts from all completed predecessor nodes */
+  includePredecessors?: boolean;
+}
+
+/**
+ * Options for routing output artifacts.
+ */
+export interface RouteOutputOptions {
+  /** Artifact reference to route */
+  artifact: ArtifactRef;
+  /** Visibility hints from the mind */
+  hints: VisibilityHints;
+}
+
+/**
+ * Interface for artifact routing in kernel sessions.
+ *
+ * The router is responsible for:
+ * 1. Determining which artifacts a node can access as inputs
+ * 2. Routing output artifacts with appropriate visibility
+ *
+ * Implementation is decoupled from storage - the router only
+ * handles visibility and routing logic, not persistence.
+ */
+export interface ArtifactRouter {
+  /**
+   * Resolve which artifacts are available as inputs for a node.
+   *
+   * This considers:
+   * - Artifacts from predecessor nodes (via edges)
+   * - Session-visible artifacts
+   * - Channel subscriptions
+   *
+   * @param context - Current routing context
+   * @param options - Optional filtering options
+   * @returns List of accessible artifact references
+   */
+  resolveInputArtifacts(
+    context: RoutingContext,
+    options?: ResolveInputOptions
+  ): Promise<ArtifactRef[]>;
+
+  /**
+   * Route output artifacts with visibility and channel assignments.
+   *
+   * This determines:
+   * - Final visibility scope (from hints or defaults)
+   * - Channel assignments
+   * - Session and node attribution
+   *
+   * @param outputs - Artifacts with visibility hints
+   * @param context - Current routing context
+   * @returns Routed artifacts with resolved metadata
+   */
+  routeOutputArtifacts(
+    outputs: RouteOutputOptions[],
+    context: RoutingContext
+  ): Promise<RoutedArtifact[]>;
+
+  /**
+   * Get default visibility for a given artifact path.
+   *
+   * Visibility can be inferred from path patterns:
+   * - `/sessions/{s}/nodes/{n}/private/**` → private
+   * - `/sessions/{s}/nodes/{n}/outputs/**` → session
+   * - `/sessions/{s}/shared/**` → session
+   * - `/persistent/**` → persistent
+   *
+   * @param path - Artifact path
+   * @param context - Routing context
+   * @returns Default visibility scope
+   */
+  getDefaultVisibility(
+    path: string,
+    context: RoutingContext
+  ): ArtifactVisibility;
+}