@sprinterai/runtime

pnpm add @sprinterai/runtime

import { AgentRegistry } from "@sprinterai/runtime";

const registry = new AgentRegistry();

// Register agents (from code or loaded from DB)
registry.register(analystAgent);
registry.register(researcherAgent);

// Look up by slug
const agent = registry.get("analyst");

import { resolveAgent } from "@sprinterai/runtime";

const resolved = await resolveAgent({
  agent: analystDefinition,
  stores,
  permissions: userPermissions,
  context: { tenantId, entityId },
});
// resolved.prompt, resolved.tools, resolved.model

import { executeAgentStream, executeAgentGenerate } from "@sprinterai/runtime";

// Streaming execution (for chat)
const stream = await executeAgentStream({
  agent: resolvedAgent,
  messages,
  onToolCall: (call) => console.log("Tool:", call.name),
});

// One-shot execution (for background tasks)
const result = await executeAgentGenerate({
  agent: resolvedAgent,
  messages,
});
// result.text, result.toolCalls, result.usage

import { buildAgentPrompt } from "@sprinterai/runtime";
import type { PromptSection } from "@sprinterai/runtime";

const sections: PromptSection[] = [
  { role: "system", content: agent.systemPrompt },
  { role: "context", content: `Tenant: ${tenantName}` },
  { role: "memory", content: memoryPrompt },
];

const prompt = buildAgentPrompt(sections);

import { createDelegateToAgentTool } from "@sprinterai/runtime";

const delegateTool = createDelegateToAgentTool({
  agentRegistry: registry,
  stores,
  permissions,
});
// Agents can use this tool to delegate tasks to other agents

import { ToolRegistry } from "@sprinterai/runtime";

const tools = new ToolRegistry();
tools.register(roiCalculator);
tools.register(dealScorer);

// Convert to AI SDK tool set
const aiToolSet = tools.toAIToolSet(permissions);

import { executeTool } from "@sprinterai/runtime";

const result = await executeTool({
  tool: roiCalculator,
  input: { investment: 1000000, returns: 1500000 },
  permissions: userPermissions,
});
// result.output, result.error, result.duration

import { createEntityTools } from "@sprinterai/runtime";

const entityTools = createEntityTools(stores.entity, permissions);
// Provides: searchEntities, getEntity, createEntity, updateEntity,
//           deleteEntity, createRelation, listEntityTypes, getEntityStats

import { toAITool, toAIToolSet } from "@sprinterai/runtime";

// Single tool
const aiTool = toAITool(roiCalculator);

// Full set with permission filtering
const toolSet = toAIToolSet(allTools, permissions);

import { resolveAgentTools, buildToolGroupMap } from "@sprinterai/runtime";

const tools = await resolveAgentTools({
  agent: agentDefinition,
  stores,
  permissions,
  includeEntityTools: true,
  includeDelegation: true,
});

// Build a slug → ToolDefinition map for a set of groups
const groupMap = buildToolGroupMap(tools, ["crm", "research"]);

import {
  hydrateToolDefinition,
  hydrateToolDefinitions,
} from "@sprinterai/runtime";
import type { ToolExecutor, HydrateToolOptions } from "@sprinterai/runtime";

// Implement ToolExecutor with your preferred sandbox
const myExecutor: ToolExecutor = {
  async execute(code: string, input: unknown): Promise<unknown> {
    // e.g. isolated-vm, Deno subprocess, edge function call
    return runInSandbox(code, input);
  },
};

const options: HydrateToolOptions = {
  executor: myExecutor,
  defaultGroups: ["custom"], // optional
};

// Single record
const tool = hydrateToolDefinition(toolRecord, options);

// Multiple records — disabled records are skipped automatically
const tools = hydrateToolDefinitions(toolRecords, options);

import { createMcpRouteHandler } from "@sprinterai/runtime";
import type {
  CreateMcpRouteHandlerConfig,
  McpRequestContext,
} from "@sprinterai/runtime";

// Configure once (module scope)
const handleMcp = createMcpRouteHandler({
  serverName: "my-app",       // reported in initialize response
  serverVersion: "1.0.0",
  protocolVersion: "2024-11-05",
});

// Next.js route handler
export async function POST(request: Request) {
  // Auth is the caller's responsibility
  const auth = await validateApiKeyAuth(supabase, request.headers.get("Authorization"));
  if (!auth) return Response.json({ error: "Unauthorized" }, { status: 401 });

  const tools = await loadToolsForTenant(auth.tenantId);

  return handleMcp(request, {
    tools,                     // ToolDefinition[] — already tenant-scoped
    permissions: auth.scopes as AppPermission[],
    executeOptions: {
      tenantId: auth.tenantId,
      source: "api",
    },
  });
}

import {
  buildMcpToolList,
  buildMcpToolExecutor,
} from "@sprinterai/runtime";
import type { McpToolInfo, McpContent, McpCallResult } from "@sprinterai/runtime";

// Filtered tool list with JSON Schema inputSchema
const toolList: McpToolInfo[] = buildMcpToolList(tools, permissions);

// Executor function that returns MCP protocol format
const executor = buildMcpToolExecutor(tools, executeOptions);
const result: McpCallResult = await executor("my-tool-slug", { key: "value" });
// result.content: McpContent[]  — [{ type: 'text', text: '...' }]
// result.isError?: boolean

import { createChatRouteHandler } from "@sprinterai/runtime";

const handler = createChatRouteHandler({
  agentRegistry: registry,
  stores,
  resolvePermissions: async (userId) => getUserPermissions(userId),
  resolveAgent: async (agentSlug) => registry.get(agentSlug),
});

export async function POST(request: Request) {
  const { stream } = await handler.handle(request);
  // toUIMessageStreamResponse() streams full UIMessage parts:
  // text tokens, tool-input, and tool-result -- making tool calls
  // visible to the client UI. Do NOT use toTextStreamResponse(),
  // which only streams raw text and hides tool calls.
  return stream.toUIMessageStreamResponse();
}

import {
  validateMessage,
  sanitizeContent,
  extractTextFromParts,
  toAIMessages,
} from "@sprinterai/runtime";

// Validate incoming message
const valid = validateMessage(rawMessage);

// Convert DB messages to AI SDK format
const aiMessages = toAIMessages(dbMessages);

import {
  buildConversationList,
  computeUnreadCount,
  getOldestReadAt,
  parseMentions,
  filterRespondingAgents,
  buildNotificationInserts,
} from "@sprinterai/runtime";
import type {
  InboxParticipantRow,
  InboxMessageRow,
  InboxUnreadMessageRow,
  InboxChatRow,
  InboxUserParticipantRow,
  NotificationInsert,
} from "@sprinterai/runtime";

const conversations = buildConversationList({
  participantRows,   // InboxUserParticipantRow[] — the user's chat memberships with last_read_at
  allParticipants,   // InboxParticipantRow[]     — all participants across those chats
  recentMessages,    // InboxMessageRow[]          — most recent message per chat
  unreadMessages,    // InboxUnreadMessageRow[]    — messages newer than oldest last_read_at
  nameMap,           // Map<string, string>        — participantId -> display name
  userId,            // string                     — current user's ID
});
// ConversationListItem[] sorted by the order of participantRows

const unreadChats = computeUnreadCount(
  participations,    // Array<{ chat_id: string; last_read_at: string }>
  recentMessages,    // InboxUnreadMessageRow[]
  userId,
);
// number — count of chats with unread messages

const cutoff = getOldestReadAt(participantRows);
// string | null — ISO timestamp, or null if rows is empty

const slugs = parseMentions("Hey @analyst and @researcher, please review");
// ["analyst", "researcher"]

const responders = filterRespondingAgents(agents, mentionedSlugs);
// agents that are auto_respond OR explicitly @mentioned, no duplicates

const inserts = buildNotificationInserts({
  participants,       // Array<{ participant_type, participant_id }>
  senderId,
  senderName,
  tenantId,
  chatId,
  content,
  mentionedSlugs,     // string[] from parseMentions()
  agentSlugToId,      // Map<string, string> — slug -> participant UUID
  tenantSlug,         // optional; omit or pass 'default' for bare /inbox/{chatId} links
});
// NotificationInsert[] — one row per non-sender user participant

import { compileEntityWorkflowDefinition, getWorkflowLayers } from "@sprinterai/runtime";

// Compile from entity type field configs into a DAG
const definition = compileEntityWorkflowDefinition(entityType);

// Get execution layers (parallel groups respecting dependencies)
const layers = getWorkflowLayers(definition);
// [[node1, node2], [node3], [node4, node5]]

import { computeWorkflowProgress, deriveWorkflowStatus } from "@sprinterai/runtime";

const progress = computeWorkflowProgress(nodeRuns);
// { total: 5, completed: 3, failed: 0, running: 1, pending: 1, percent: 60 }

const status = deriveWorkflowStatus(nodeRuns);
// "running" | "completed" | "failed" | "pending"

import {
  getWorkflowRunHistory,
  getActiveWorkflowRuns,
  getRecentWorkflowRuns,
  getWorkflowActivitySummary,
} from "@sprinterai/runtime";
import type { WorkflowActivitySummary } from "@sprinterai/runtime";

interface WorkflowActivitySummary {
  active: number;          // running + waiting_human + partial
  waitingHuman: number;    // subset of active awaiting human input
  completedToday: number;  // completed since midnight UTC
  failedToday: number;     // failed since midnight UTC
}

import {
  expireStaleWorkflowNodeClaims,
  hasActiveClaims,
  findStaleNodeRuns,
  DEFAULT_CLAIM_TIMEOUT_MS,
} from "@sprinterai/runtime";

const expired = await expireStaleWorkflowNodeClaims(workflowRunStore);
// expired: number — how many stale claims were released

const stale = findStaleNodeRuns(nodeRuns, 5 * 60_000); // 5-minute threshold

import {
  uploadDocument,
  getDocumentPages,
  getDocumentPage,
  searchDocumentPages,
  searchAllDocuments,
  linkDocumentToEntity,
  unlinkDocumentFromEntity,
  deleteDocument,
  getDocumentUrl,
  DOCUMENT_RELATIONSHIP_TYPE,
  DEFAULT_URL_EXPIRY_SECONDS,
} from "@sprinterai/runtime";

import type { UploadDocumentStore } from "@sprinterai/runtime";

const doc = await uploadDocument(store, {
  tenantId,
  title: "Q3 Report",
  fileData: buffer,
  mimeType: "application/pdf",
});
// doc: DocumentRecord

import type { DocumentPageStore } from "@sprinterai/runtime";

// All pages, sorted by page_number ascending
const pages = await getDocumentPages(store, documentId);

// A specific page (1-based)
const page = await getDocumentPage(store, documentId, 3);
// null if the page does not exist

import type { DocumentSearchStore } from "@sprinterai/runtime";

// Search within one document
const results = await searchDocumentPages(store, documentId, "revenue forecast", { limit: 10 });

// Search across all documents for a tenant, optionally restricting to a subset
const results = await searchAllDocuments(store, tenantId, "due diligence", {
  limit: 25,
  documentIds: ["doc-a", "doc-b"], // optional — applied client-side post-query
});

import type { DocumentLinkStore } from "@sprinterai/runtime";

// Create a link: entity -> document entity
await linkDocumentToEntity(store, documentId, entityId, tenantId);

// Remove the link
await unlinkDocumentFromEntity(store, documentId, entityId, tenantId);

import type { DocumentDeletionStore } from "@sprinterai/runtime";

await deleteDocument(store, documentId);
// Cascades to chunks/pages and removes the storage file

import type { DocumentUrlStore } from "@sprinterai/runtime";

// Default expiry: 1 hour (DEFAULT_URL_EXPIRY_SECONDS = 3600)
const url = await getDocumentUrl(store, documentId);

// Custom expiry
const url = await getDocumentUrl(store, documentId, 300); // 5 minutes

import { createAnalyticsRecorder, createAnalyticsHooks } from "@sprinterai/runtime";
import type { AnalyticsHooks } from "@sprinterai/runtime";

import { createAnalyticsRecorder } from "@sprinterai/runtime";
import { SupabaseAnalyticsProvider } from "@sprinterai/supabase";

const recordEvent = createAnalyticsRecorder({
  providers: [new SupabaseAnalyticsProvider(supabaseClient)],
  onError: (provider, error) => console.error("Analytics error:", error),
});

const analytics = createAnalyticsHooks(recordEvent);

// Entity lifecycle
analytics.onEntityMutation("created", entity.id, "company", tenantId, userId);

// Workflow run
analytics.onWorkflowRun("completed", workflowId, tenantId, userId, { duration: 4200 });

// Tool execution
analytics.onToolExecution(toolId, tenantId, userId);

// Agent invocation / delegation
analytics.onAgentInvocation("analyst", tenantId, userId);
analytics.onAgentDelegation("coordinator", "analyst", tenantId, userId);

// Chat
analytics.onChatMessageSent(conversationId, tenantId, userId);

// Search
analytics.onSearchPerformed(query, tenantId, userId, { results: 12 });

import { createViewPermissionEnforcer } from "@sprinterai/runtime";
import type { ViewPermissionEnforcer } from "@sprinterai/runtime";

const enforcer = createViewPermissionEnforcer(stores.view, {
  tenantId,
  userId,
  permissions: userPermissions,
});

// Returns only views the caller can access
const views = await enforcer.listViews();

// Returns null for inaccessible views (no information leakage)
const view = await enforcer.getView(idOrSlug);

// Throws 'Permission denied' if not authorized
await enforcer.updateView(idOrSlug, { title: "New Title" });

// Throws 'Permission denied' if not authorized
await enforcer.deleteView(idOrSlug);

import { createCommentHandler } from "@sprinterai/runtime";
import type { CommentHandler } from "@sprinterai/runtime";

const handler = createCommentHandler({
  store: commentStore,
  onCommentCreated: (comment) => auditLog("comment.created", comment.id),
  onCommentUpdated: (comment) => auditLog("comment.updated", comment.id),
  onCommentDeleted: (commentId, entityId) => auditLog("comment.deleted", commentId),
});

// Threaded tree (flat → tree conversion)
const threads = await handler.getThreadedComments(entityId);
// threads[0].replies[0].replies — fully nested

// Flat list
const flat = await handler.getComments(entityId);

// Total comment count
const count = await handler.getCommentCount(entityId);

// Create top-level comment
const comment = await handler.createComment({
  tenantId, entityId, userId,
  content: "Looks good to me",
});

// Create a reply (validates parent exists in the same entity)
const reply = await handler.createComment({
  tenantId, entityId, userId,
  content: "Agreed",
  parentId: comment.id,
});

// Update content
await handler.updateComment(comment.id, "Updated text");

// Delete
await handler.deleteComment(comment.id, entityId);

import { buildCommentThread, countComments, getReplyCount } from "@sprinterai/runtime";

// Convert flat CommentRecord[] to ThreadedComment[] (sorted by created_at)
const tree = buildCommentThread(flatComments);

// Total count of all comments in a flat list
const total = countComments(flatComments);

// Number of direct replies to a specific comment
const replies = getReplyCount(flatComments, commentId);

import { createAuditContext, generateCorrelationId } from "@sprinterai/runtime";
import type { AuditContext } from "@sprinterai/runtime";

// New context with a generated correlation ID
const ctx = createAuditContext(auditStore, tenantId);

// Continue an existing trace
const ctx = createAuditContext(auditStore, tenantId, existingCorrelationId);

// Log a single entry (correlationId is injected into entry.details)
const log = await ctx.log({
  table_name: "entities",
  record_id: entityId,
  changed_by: userId,
  operation: "UPDATE",
  details: { fields_changed: ["stage"] },
});

// Log multiple entries sharing the same correlationId
const logs = await ctx.batchLog([
  { table_name: "entities", record_id: id1, changed_by: userId, operation: "UPDATE", details: {} },
  { table_name: "entities", record_id: id2, changed_by: userId, operation: "UPDATE", details: {} },
]);

// Access the generated/provided correlation ID for downstream use
const { correlationId } = ctx;

import { mean, median, min, max, aggregateScores } from "@sprinterai/runtime";

const scores = [85, 90, 78, 92];
mean(scores);   // 86.25
median(scores); // 87.5
min(scores);    // 78
max(scores);    // 92

// Aggregate across multiple dimensions
const aggregation = aggregateScores(responses, criteriaSet);

import { runEval, exactMatch, fuzzyMatch, contains } from "@sprinterai/runtime";

const result = await runEval({
  target: async (input) => agent.generate(input),
  dataset: [
    { input: "What is 2+2?", expected: "4" },
    { input: "Capital of France?", expected: "Paris" },
  ],
  scorers: [exactMatch, fuzzyMatch],
});
// result.scores, result.passed, result.details

import { loadMemories, buildMemoryPrompt } from "@sprinterai/runtime";

const memories = await loadMemories({
  store: stores.memory,
  agentSlug: "analyst",
  userId: user.id,
  tenantId,
});

const prompt = buildMemoryPrompt(memories);
// Inject into agent system prompt

import {
  runInputGuardrails,
  runOutputGuardrails,
  runGuardrails,
} from "@sprinterai/runtime";

// Run input guardrails before LLM call
const inputResult = await runInputGuardrails(guardrails.input, userMessage);
if (!inputResult.passed) {
  return inputResult.reason;
}

// Run output guardrails after LLM response
const outputResult = await runOutputGuardrails(guardrails.output, agentResponse);

import {
  discoverMCPTools,
  createA2AAgent,
  createOpenClawModel,
  createHTTPAgent,
} from "@sprinterai/runtime";
import type { MCPAdapterConfig } from "@sprinterai/runtime";

// MCP tool discovery — basic
const mcpTools = await discoverMCPTools({
  serverUrl: "http://localhost:3001",
  client: myMcpClient,
});

// MCP tool discovery — multi-server with slug namespacing
// Tool slugs become "mcp-github-search", "mcp-github-list-repos", etc.
// Without serverPrefix they would be "mcp-search", "mcp-list-repos"
const githubTools = await discoverMCPTools({
  serverUrl: "https://mcp.github.example.com",
  client: githubMcpClient,
  serverPrefix: "github",
});

// Agent-to-Agent protocol
const a2aAgent = createA2AAgent({ endpoint: "https://agent.example.com/a2a" });

// OpenClaw model adapter
const model = createOpenClawModel({ apiKey: process.env.OPENCLAW_KEY });

// Generic HTTP agent
const httpAgent = createHTTPAgent({ baseUrl: "https://api.example.com/agent" });

import { batchUpsertEntities } from "@sprinterai/runtime";
import type { ImportEntityStore, ParsedRow, UpsertOptions, BatchUpsertResult } from "@sprinterai/runtime";

const rows: ParsedRow[] = [
  { title: "Acme Corp", content: { domain: "acme.com", stage: "active" } },
  { title: "Beta Inc",  content: { domain: "beta.io",  stage: "prospect" } },
];

const result: BatchUpsertResult = await batchUpsertEntities(
  store,          // ImportEntityStore
  "account",      // entity type slug
  rows,
  { matchKey: "domain", overwrite: false },
);
// { created: 1, updated: 1, skipped: 0, failed: 0, errors: [] }

import { matchRowsForUpsert } from "@sprinterai/runtime";

const { matched, skippedCount } = await matchRowsForUpsert(store, "account", rows, "domain");
// matched[i].existingId — null means create, string means update
// matched[i].skipped    — true when match-key cell was empty

import { mergeContent } from "@sprinterai/runtime";

const merged = mergeContent(
  { stage: "prospect", domain: "acme.com" },
  { stage: "active",   revenue: 5000000 },
  true, // overwrite
);
// { stage: "active", domain: "acme.com", revenue: 5000000 }

import { resolveRelationColumns } from "@sprinterai/runtime";
import type { RelationColumnStore } from "@sprinterai/runtime";

const columns = {
  activity_count: {
    label: "Activity Count",
    relatedTypeSlug: "activity",
    relationshipType: "has_activity",
    aggregation: "count",
  },
  last_call: {
    label: "Last Call",
    relatedTypeSlug: "activity",
    relationshipType: "has_activity",
    aggregation: "latest",
    field: "date",
    filters: [{ field: "activity_type", operator: "eq", value: "call" }],
  },
};

const result = await resolveRelationColumns(entityIds, columns, store);
// {
//   "entity-1": { activity_count: 12, last_call: "2026-03-15" },
//   "entity-2": { activity_count:  4, last_call: null },
// }

interface RelationColumnStore {
  queryRelationsByTarget(targetEntityIds: string[], relationshipType: string): Promise<EntityRelationRow[]>;
  queryRelationsBySource(sourceEntityIds: string[], relationshipType: string): Promise<EntityRelationRow[]>;
  getEntitiesByIds(ids: string[], typeSlug: string): Promise<RelatedEntityRow[]>;
}

import { createEmailEngine } from "@sprinterai/runtime/email";
import type { EmailEngine, EmailEngineOptions } from "@sprinterai/runtime/email";

import { createEmailEngine } from "@sprinterai/runtime/email";
import type { EmailProvider } from "@sprinterai/core";

// Bring your own provider (e.g. Resend, SendGrid, SMTP adapter)
const myProvider: EmailProvider = {
  async send(message) {
    const res = await resend.emails.send(message);
    return { id: res.data?.id ?? "", success: !res.error };
  },
};

const email = createEmailEngine({
  provider: myProvider,
  config: {
    apiKey: process.env.EMAIL_API_KEY!,
    fromAddress: "noreply@example.com",
    fromName: "My App",
  },
});

interface EmailEngine {
  // Send a raw email. Input is validated against SendEmailInputSchema.
  send(input: SendEmailInput): Promise<SendEmailResult>;

  // Render and send a notification email.
  sendNotification(
    to: string,
    subject: string,
    ctx: NotificationEmailContext,
  ): Promise<SendEmailResult>;

  // Render and send a digest email.
  sendDigest(
    to: string,
    subject: string,
    ctx: DigestEmailContext,
  ): Promise<SendEmailResult>;
}

import {
  renderNotificationEmail,
  renderDigestEmail,
  renderInviteEmail,
  renderTempPasswordEmail,
  renderPasswordResetEmail,
} from "@sprinterai/runtime/email";

interface InviteEmailContext {
  recipientName: string;
  tenantName: string;
  inviterName: string;
  tempPassword: string;
  loginUrl: string;
  email: string;
}

interface TempPasswordEmailContext {
  recipientName: string;
  tenantName: string;
  tempPassword: string;
  loginUrl: string;
  email: string;
}

interface PasswordResetEmailContext {
  recipientName: string;
  tenantName: string;
  resetUrl: string;
}

import type { EmailProvider } from "@sprinterai/core";

interface EmailProvider {
  send(message: EmailMessage): Promise<SendEmailResult>;
  sendBatch?(messages: EmailMessage[]): Promise<{ ids: string[] }>;
}

import {
  resolveModel,
  getModelConfig,
  listModels,
  getDefaultModel,
  createProviderRegistry,
  MODEL_REGISTRY,
} from "@sprinterai/runtime";
import type {
  ModelConfig,
  ModelFilter,
  ModelFactory,
  ProviderRegistry,
} from "@sprinterai/runtime";

interface ModelConfig {
  id: string;                // Canonical ID, e.g. 'claude-sonnet-4-6'
  provider: ModelProvider;   // Sourced from @sprinterai/core
  modelId: string;           // Provider-specific ID passed to the AI SDK
  displayName: string;
  contextWindow?: number;
  maxOutputTokens?: number;
  supportsVision?: boolean;
  supportsTools?: boolean;
  capabilities?: ModelCapability[]; // Full capability flags from @sprinterai/core
  speedTier?: 'fast' | 'medium' | 'slow';
  reasoningLevel?: 'low' | 'medium' | 'high' | null;
  costPer1kInput?: number;   // USD per 1,000 input tokens
  costPer1kOutput?: number;  // USD per 1,000 output tokens
}

import { anthropic } from "@ai-sdk/anthropic";
import { openai } from "@ai-sdk/openai";

const providers = createProviderRegistry({
  anthropic: (id) => anthropic(id),
  openai: (id) => openai(id),
  google: (id) => google(id),
});

const model = resolveModel("claude-sonnet-4-6", providers);
// Returns an AI SDK LanguageModel ready for streamText / generateText

// Look up a single entry
const config = getModelConfig("gpt-4o");

// List with optional filtering
const visionModels = listModels({ supportsVision: true });
const anthropicModels = listModels({ provider: "anthropic" });

// Get the default model (GPT-4o)
const defaultConfig = getDefaultModel();

import {
  InMemoryEntityStore,
  InMemoryAgentStore,
  InMemoryChatStore,
  InMemoryTenantStore,
  InMemoryToolStore,
  InMemoryTaskStore,
  InMemoryMemoryStore,
} from "@sprinterai/runtime";

const stores = {
  entity: new InMemoryEntityStore(),
  agent: new InMemoryAgentStore(),
  chat: new InMemoryChatStore(),
  tenant: new InMemoryTenantStore(),
  tool: new InMemoryToolStore(),
  task: new InMemoryTaskStore(),
  memory: new InMemoryMemoryStore(),
};

import { loadModules, createPlatformRuntime } from "@sprinterai/runtime";

// Load and validate modules
const loaded = loadModules([dealFlow, portfolioModule]);
// loaded.entityTypes, loaded.agents, loaded.tools

// Create full runtime
const runtime = createPlatformRuntime({
  modules: [dealFlow, portfolioModule],
  stores: supabaseStores,
});
// runtime.agents, runtime.tools, runtime.stores

import {
  cronToHuman,
  getNextRun,
  buildParserSystemPrompt,
  AutomationPlanSchema,
} from "@sprinterai/runtime/automation";
import type { AutomationPlan } from "@sprinterai/runtime/automation";

cronToHuman('0 9 * * *');         // "Daily at 9 AM"
cronToHuman('0 9 * * 1-5');       // "Weekdays at 9 AM"
cronToHuman('*/15 * * * *');      // "Every 15 minutes"
cronToHuman('0 */4 * * *');       // "Every 4 hours"
cronToHuman('0 0 1 * *');         // "Monthly on the 1st"
cronToHuman('5 4 2 3 *');         // "5 4 2 3 *"  (unknown, returned as-is)

import { CronExpressionParser } from 'cron-parser';

const nextRun = getNextRun('0 9 * * *', {
  now: new Date(),
  timezone: 'America/New_York',
  parser: CronExpressionParser,
});
// "2026-04-04T13:00:00.000Z"  (ISO string)

// Without a parser, always returns null
getNextRun('0 9 * * *'); // null

import { generateObject } from 'ai';
import {
  AutomationPlanSchema,
  buildParserSystemPrompt,
} from "@sprinterai/runtime/automation";

const entityTypes = [
  { slug: 'account', name: 'Account', description: 'Portfolio company' },
  { slug: 'contact', name: 'Contact' },
];

const { object } = await generateObject({
  model: yourModel,
  schema: AutomationPlanSchema,
  system: buildParserSystemPrompt(entityTypes),
  prompt: 'Monitor news for our portfolio companies every morning at 9am',
});

// object satisfies AutomationPlan:
// {
//   name: "Portfolio News Monitor",
//   slug: "portfolio-news-monitor",
//   description: "Monitors news for portfolio companies each morning",
//   entityTypeSlug: "account",
//   schedule: "0 9 * * *",
//   scheduleHuman: "Daily at 9 AM",
//   prompt: "Search for recent news...",
//   icon: "search",
// }

import {
  matchEntityCreatedTriggers,
  matchFieldChangedTriggers,
  executeAutomationWorkflow,
} from "@sprinterai/runtime";
import type {
  EntityEvent,
  AutomationCandidate,
  TriggerMatch,
  AutomationStepExecutor,
  AutomationRunTracker,
  ExecuteAutomationWorkflowInput,
  ExecuteAutomationWorkflowResult,
} from "@sprinterai/runtime";

const event: EntityEvent = {
  entityId: "ent-123",
  tenantId: "ten-abc",
  entityTypeSlug: "account",
  currentContent: { stage: "closed" },
  previousContent: { stage: "active" },
};

// Match entity_created triggers
const created = matchEntityCreatedTriggers(event, automations);

// Match field_changed triggers (requires both previousContent and currentContent)
const changed = matchFieldChangedTriggers(event, automations);
// changed[0].automationId, changed[0].runGroupId

interface TriggerMatch {
  automationId: string;
  runGroupId: string;  // Stable idempotency key: "<trigger>:<entityId>:<automationId>:<timestamp>"
}

const result = await executeAutomationWorkflow({
  automationId: match.automationId,
  tenantId: "ten-abc",
  triggerType: "field_changed",
  triggerEntityId: "ent-123",
  runGroupId: match.runGroupId,
  steps: automation.content.steps,
  automationTitle: automation.content.title,
  stepExecutor: myStepExecutor,   // AutomationStepExecutor
  runTracker: myRunTracker,       // AutomationRunTracker
});
// {
//   runId: "run-xyz",
//   status: "completed" | "partial" | "failed",
//   stepCount: 3,
//   completedCount: 2,
//   failedCount: 1,
// }

interface AutomationStepExecutor {
  execute(params: {
    agentSlug: string;
    tenantId: string;
    prompt: string;
    label: string;
    automationTitle: string;
  }): Promise<void>;
}

interface AutomationRunTracker {
  createRun(params: CreateAutomationRunParams): Promise<{ id: string }>;
  updateStepStatus(
    runId: string,
    stepKey: string,
    status: string,
    details?: { errorMessage?: string; durationMs?: number },
  ): Promise<void>;
  completeRun(
    runId: string,
    status: 'completed' | 'partial' | 'failed',
    durationMs: number,
  ): Promise<void>;
}

import {
  shouldRunNow,
  filterScheduledAutomations,
} from "@sprinterai/runtime";
import type { CronAutomationCandidate } from "@sprinterai/runtime";

shouldRunNow('0 9 * * *', new Date('2026-04-04T09:00:00'));   // true
shouldRunNow('0 9 * * 1-5', new Date('2026-04-05T09:00:00')); // false (Saturday)
shouldRunNow('*/15 * * * *', new Date('2026-04-04T09:15:00')); // true
shouldRunNow('0 */4 * * *', new Date('2026-04-04T08:00:00'));  // true
shouldRunNow('bad expression'); // false

interface CronAutomationCandidate {
  id: string;
  schedule: string;     // 5-field cron expression
  timezone?: string;    // accepted but not applied — pass UTC-normalised `now` for timezone precision
  enabled: boolean;
  lastRunStatus?: string | null;
}

const due = filterScheduledAutomations(automations, now);
// CronAutomationCandidate[] — subset whose schedule matches `now`

import {
  exportToVault,
  importFromVault,
  syncWikilinkRelations,
} from "@sprinterai/runtime";
import type {
  VaultExportInput,
  VaultExportResult,
  VaultExportFile,
  VaultImportInput,
  VaultImportResult,
  SyncWikilinkRelationsResult,
  VaultExportStore,
  EntityUpsertStore,
  WikilinkResolver,
  WikilinkSyncStore,
} from "@sprinterai/runtime";

const result: VaultExportResult = await exportToVault({
  entityStore,   // VaultExportStore — requires list(tenantId, filters?)
  tenantId,
  entityTypeSlug: "account",  // optional — filter by type
  entityIds: ["id-1", "id-2"], // optional — filter by IDs
  limit: 500,                 // default: 500
});
// result.files: VaultExportFile[]  — { path, content }
// result.count: number

const result: VaultImportResult = await importFromVault({
  files: [{ path: "account/acme.md", content: markdownString }],
  tenantId,
  entityStore,         // EntityUpsertStore
  wikilinkResolver,    // optional WikilinkResolver
  validEntityTypes: ["account", "contact"],
  slugify: (title) => mySlugFn(title), // optional — defaults to lowercase + hyphens + timestamp
});
// { created: number, updated: number, skipped: number, errors: Array<{ path, error }> }

const result: SyncWikilinkRelationsResult = await syncWikilinkRelations(
  entityId,
  tenantId,
  bodyText,
  store, // WikilinkSyncStore
);
// { resolved: number, unresolved: string[] }

import {
  resolveSettings,
  shouldShowDashboardRoleHint,
} from "@sprinterai/runtime/settings";

const merged = resolveSettings([
  { value: { theme: { primary: '#1a1a1a', radius: 8 }, aiLimits: { maxTokens: 10000 } } },
  { value: { theme: { primary: '#3B82F6' } } },            // tenant override
  { value: { theme: { radius: 4 }, aiLimits: { maxTokens: 50000 } } }, // user override
]);
// {
//   theme: { primary: '#3B82F6', radius: 4 },
//   aiLimits: { maxTokens: 50000 },
// }

shouldShowDashboardRoleHint(null, 0);                              // true  — new user, no activity
shouldShowDashboardRoleHint({ onboardingCompleted: true }, 0);     // false — already completed
shouldShowDashboardRoleHint({ jobFunction: 'sales' }, 0);          // false — already selected
shouldShowDashboardRoleHint(null, 5);                              // false — has existing activity

import { createTemplateCloner } from "@sprinterai/runtime/template";
import type {
  TemplateCloner,
  TemplateClonerStores,
  TemplateClonerConfig,
} from "@sprinterai/runtime/template";

const cloner = createTemplateCloner({ stores: myClonerStores });

interface TemplateClonerStores {
  createEntityType(input: { tenantId, slug, name, schema, config?, description?, icon?, color? }): Promise<{ id, slug }>;
  entityTypeExists(tenantId: string, slug: string): Promise<boolean>;
  createView(input: { tenantId, title, description?, entityTypeSlug?, blocks, layout, pageType? }): Promise<{ id }>;
  createEntity(input: { tenantId, typeSlug, title, content, tags? }): Promise<{ id }>;
  updateNavConfig(tenantId: string, navConfig: Record<string, unknown>): Promise<void>;
  updateTheme(tenantId: string, theme: Record<string, unknown>): Promise<void>;
}

const result = await cloner.applyTemplate(template, tenantId, {
  createSampleEntities: true,   // default: false
  updateNavigation: true,       // default: true
  applyTheme: false,            // default: false
});
// {
//   entityTypesCreated: 3,
//   agentsCreated: 0,
//   viewsCreated: 2,
//   sampleEntitiesCreated: 5,
//   navigationUpdated: true,
//   themeUpdated: false,
// }

const snapshot = await cloner.snapshotTenant(tenantId, {
  name: 'PE Deal Flow Template',
  description: 'Standard deal flow workspace for PE firms',
});
// snapshot omits id, created_at, updated_at (server-managed fields)

import {
  resolveFeed,
  resolveFeedPage,
  buildFeedDelta,
  resolveDigest,
  resolveMultiDayDigest,
  computeForYouScores,
  sortByScore,
  filterByScore,
  rowToFeedItem,
  rowsToFeedItems,
  extractFeedPreview,
  formatActivityPlainText,
  getTimeRangeStart,
} from "@sprinterai/runtime";
import type {
  FeedItem,
  FeedConfig,
  FeedTimeRange,
  FeedTab,
  FeedDigest,
  DigestConfig,
  RankingInput,
} from "@sprinterai/runtime";

interface FeedConfig {
  tenantId: string;
  userId: string;
  tab: FeedTab;             // 'all' | 'for-you' | 'digest'
  timeRange: FeedTimeRange; // 'today' | 'yesterday' | 'week' | 'month' | 'all'
  entityId?: string;        // filter to a specific entity
  actorId?: string;         // filter by actor (user or agent)
  action?: string;          // filter by activity action
  limit?: number;           // default: 50
  before?: string;          // ISO timestamp cursor for pagination
  includeImportance?: boolean;
  recencyWeight?: number;   // 0-1, default: 0.7
  importanceWeight?: number; // 0-1, default: 0.3
}

// Full feed query with optional time range filter
const items = await resolveFeed(activityStore, config);

// With time range applied (uses getTimeRangeStart to set `before` cursor)
const items = await resolveFeedWithTimeFilter(activityStore, config);

// Paginated page (cursor-based)
const page = await resolveFeedPage(activityStore, config);

// Delta — items in newItems that are not in prevItems (for live polling)
const delta = buildFeedDelta(prevItems, newItems);

// Score a batch of items in-place
const ranked = sortByScore(items);

// Filter items below a relevance threshold (0-100)
const filtered = filterByScore(items, 30);

// Low-level: compute a single item's score
const score = computeForYouScores({
  createdAt: item.created_at,
  importance: item.metadata?.importance ?? 0,
  now: new Date(),
  recencyWeight: 0.7,
  importanceWeight: 0.3,
});

import type { DigestConfig, FeedDigest } from "@sprinterai/runtime";

const digestConfig: DigestConfig = {
  ...feedConfig,
  digestLimit: 10,        // max items in digest
  minScoreThreshold: 20,  // drop low-relevance items
  includeRecent: true,
};

// Last 24 hours
const digest = await resolveDigest(activityStore, digestConfig);
// { date, tenantId, items, summary, emailSubject, emailPreview }

// Multi-day digest
const weekly = await resolveMultiDayDigest(activityStore, digestConfig, 7);

// Row → FeedItem (single and batch)
const item  = rowToFeedItem(activityRecord);
const items = rowsToFeedItems(activityRecords);

// Display extraction
const preview  = extractFeedPreview(item);   // short text summary
const actor    = extractActorDisplay(item);  // actor display name
const entity   = extractEntityDisplay(item); // entity title
const plain    = formatActivityPlainText(item); // "Actor action Entity"

import type {
  ExtractionStore,
  ExtractionRunRecord,
  ExtractionResultRecord,
  CreateExtractionRunInput,
  CreateExtractionResultInput,
  ActivityStore,
  ActivityRecord,
  ListActivitiesOptions,
  ActivityGroup,
} from "@sprinterai/runtime";

import {
  createHeartbeatRun,
  completeHeartbeatRun,
  failHeartbeatRun,
  getHeartbeatRunHistory,
  getAllRecentHeartbeatRuns,
  cleanupStaleHeartbeatRuns,
} from "@sprinterai/runtime";
import type {
  CreateHeartbeatRunOptions,
  CompleteHeartbeatRunMetrics,
  HeartbeatRunStore,
} from "@sprinterai/runtime";

// Create a run with optional idempotency key (prevents duplicates on scheduler restart)
const run = await createHeartbeatRun(store, agentId, {
  tenantId,
  triggerType: "scheduled",    // "scheduled" | "manual" | "api"
  prompt: "Morning briefing",  // optional override prompt
  idempotencyKey: "2026-04-03-09:00", // optional
});

// Mark completed with optional metrics
await completeHeartbeatRun(store, run.id, {
  tokensUsed: 1200,
  costCents: 3,
  durationMs: 5400,
});

// Mark failed with error info
await failHeartbeatRun(store, run.id, new Error("API timeout"));

// Run history for a specific agent (newest first, default limit: 20)
const history = await getHeartbeatRunHistory(store, agentId, 50);

// All recent runs across agents for a tenant (default limit: 100)
const recent = await getAllRecentHeartbeatRuns(store, tenantId);

// Expire stale running claims (returns count cleaned up)
const cleaned = await cleanupStaleHeartbeatRuns(store, 15 * 60_000); // 15 min

import {
  createAgentVersion,
  getVersionHistory,
  rollbackToVersion,
} from "@sprinterai/runtime";
import type { AgentVersionStore } from "@sprinterai/runtime";

// Create a new version (auto-incremented version number)
const version = await createAgentVersion(store, agentId, {
  agentConfig: currentConfig,
  systemPrompt: "You are...",
  model: "claude-sonnet-4-6",
  changeSummary: "Added portfolio analysis tool",
});

// Version history (newest first, default limit: 20)
const history = await getVersionHistory(store, agentId, 10);

// Roll back — snapshots current config as a new version before overwriting
await rollbackToVersion(versionStore, agentStore, agentId, targetVersionId);

import {
  createToolSession,
  getToolSession,
  getToolSessionByToken,
  completeToolSession,
  listSessionSubmissions,
} from "@sprinterai/runtime";
import type { CreateToolSessionOptions } from "@sprinterai/runtime";

// Create a session
const session = await createToolSession(store, tenantId, {
  toolSlug: "deal-scorer",
  title: "Q1 Pipeline Review",
  entityIds: ["entity-1", "entity-2"],
  config: { scoreModel: "v2" },
  createdBy: userId,
});
// session.token — shareable public access token

// Retrieve by session ID (tenant-scoped)
const session = await getToolSession(store, sessionId);

// Retrieve by public token (no tenant check — for shared/public links)
const session = await getToolSessionByToken(store, token);

// Complete a session
await completeToolSession(store, sessionId);

// List all submissions for a session
const runs = await listSessionSubmissions(store, sessionId);

import {
  bulkDeleteEntities,
  bulkAddTags,
  bulkRemoveTags,
  bulkUpdateField,
  DEFAULT_BATCH_SIZE,
} from "@sprinterai/runtime";
import type { BulkOperationResult } from "@sprinterai/runtime";

interface BulkOperationResult {
  succeeded: number;
  failed: number;
  errors: Array<{ id: string; error: string }>;
}

// Delete entities in batches
const result = await bulkDeleteEntities(entityIds, store);

// Add tags — merges with each entity's existing tags
const result = await bulkAddTags(entityIds, ["verified", "q1-pipeline"], store);

// Remove tags — no-ops silently for entities that don't have the tag
const result = await bulkRemoveTags(entityIds, ["archived"], store);

// Update a field on all entities (merges into content)
const result = await bulkUpdateField(entityIds, "stage", "due-diligence", store);

// Custom batch size
const result = await bulkDeleteEntities(entityIds, store, 100);

import {
  shareEntityWithUser,
  removeEntityShare,
  getEntityShares,
  updateEntityVisibility,
  generateShareToken,
  getEntityByShareToken,
} from "@sprinterai/runtime";
import type {
  EntityShareRole,
  EntityVisibility,
  EntityShareRecord,
  ShareLinkRecord,
  ShareAccessResult,
  UserShareStore,
  ShareStore,
} from "@sprinterai/runtime";

// Grant access — upsert semantics (updates role if already shared)
const share = await shareEntityWithUser(entityId, userId, "editor", userShareStore);

// Revoke access — no-op if not shared
await removeEntityShare(entityId, userId, userShareStore);

// List all shares for an entity
const shares = await getEntityShares(entityId, userShareStore);

// Change entity visibility
await updateEntityVisibility(entityId, "shared", entityStore);
// Visibility values: 'private' | 'shared' | 'tenant' | 'public'

// Generate a shareable link (default role: 'viewer', default expiry: 30 days)
const link = await generateShareToken(entityId, shareStore, {
  role: "viewer",
  expiresInDays: 7,
});
// link.token — embed in a shareable URL

// Resolve a token to entity access
const access = await getEntityByShareToken(token, shareStore);
// null if token unknown, expired, or inactive
// access.entity, access.role, access.shareRecord

import {
  createCollectionShare,
  deleteCollectionShare,
  listCollectionShares,
} from "@sprinterai/runtime";
import type {
  CreateCollectionShareInput,
  CollectionShareRecord,
  CollectionShareStore,
} from "@sprinterai/runtime";

const collection = await createCollectionShare({
  entityTypeSlug: "opportunity",
  userId,
  tenantId,
  filters: [{ field: "stage", operator: "eq", value: "screening" }],
  minScore: 70,
}, store);

const collections = await listCollectionShares(userId, store);
await deleteCollectionShare(collectionId, store);

import {
  buildRelationInserts,
  createEntityRelation,
  deleteEntityRelation,
  getRelatedEntities,
  syncEntityRelationsFromConfig,
} from "@sprinterai/runtime";
import type {
  EntityRelationCrudStore,
  RelatedEntityWithRelation,
} from "@sprinterai/runtime";

// Create a typed relation between two entities
await createEntityRelation(store, fromEntityId, toEntityId, "has_activity");

// Delete by relation ID
await deleteEntityRelation(store, relationId);

// List all related entities for an entity (with their relation metadata)
const related = await getRelatedEntities(store, entityId);
// related[i].entity, related[i].relation

// Sync from a config map — adds missing, removes stale
await syncEntityRelationsFromConfig(store, entityId, relationConfigs, relationsMap);

const inserts = buildRelationInserts(
  relationConfigs,
  relationsMap,
  entityId,
  tenantId,
);
// Array<Omit<EntityRelationRecord, 'created_at'>>

import {
  promoteFieldValue,
  promoteFieldValueAdmin,
} from "@sprinterai/runtime";
import type { PromoteFieldValueStores } from "@sprinterai/runtime";

const stores: PromoteFieldValueStores = {
  response: responseStore,
  entity: entityStore,
};

// Validates response exists, belongs to entity, and is not terminal
await promoteFieldValue(stores, responseId, "revenue", entityId);

// Admin bypass — skips status validation
await promoteFieldValueAdmin(stores, responseId, "revenue", entityId);

import {
  loadMemories,
  buildMemoryPrompt,
  createUserMemory,
  createMemoryAsAgent,
  deleteUserMemory,
} from "@sprinterai/runtime";

// Create a memory attributed to the user
const memory = await createUserMemory(store, userId, "Prefers concise summaries", "user");

// Create a memory attributed to an agent (source set to agent ID)
const memory = await createMemoryAsAgent(store, userId, "User is interested in SaaS deals", agentId);

// Delete a specific memory
await deleteUserMemory(store, memoryId);

import {
  upsertSharedContext,
  deleteSharedContext,
  loadSharedContextPrompt,
  buildCorrectionsPrompt,
  buildLessonsPrompt,
  buildRoutingPrompt,
  CONTEXT_KEYS,
} from "@sprinterai/runtime";
import type {
  SharedContextStore,
  SharedContextRecord,
} from "@sprinterai/runtime";

// Upsert by key (creates if not exists, updates if exists)
const record = await upsertSharedContext(
  store,
  "corrections",
  "Always cite sources when referencing market data",
  tenantId,
);

// Delete a context entry
await deleteSharedContext(store, "corrections", tenantId);

import { createExternalDataReceiver } from "@sprinterai/runtime";
import type {
  ExternalDataReceiverConfig,
  ReceiveWebhookOptions,
  WebhookReceiveResult,
  ExternalDataReceiver,
} from "@sprinterai/runtime";

import type { ExternalDataStore } from "@sprinterai/core";

const receiver = createExternalDataReceiver({ store: externalDataStore });

// In your POST /api/webhooks/:token route handler:
const result = await receiver.receiveWebhook({
  token: params.token,
  rawBody: await request.text(),      // raw string, not parsed
  headers: Object.fromEntries(request.headers), // lowercase keys
});
// { success: boolean; pointsCreated: number; error?: string }

import { extractByPath } from "@sprinterai/runtime";

const data = { results: { metrics: [{ key: "rev", value: 100 }] } };
const metrics = extractByPath(data, "results.metrics");
// [{ key: "rev", value: 100 }]

import {
  getSourceValidationStatus,
  resolveSourceSyncStatus,
  canRunSourceSync,
  isSourceDue,
  createSourcePoller,
} from "@sprinterai/runtime";
import type {
  ValidationStatus,
  FetchedItem,
  SourceFetchResult,
  SourcePollSummary,
  SourcePollerConfig,
  SourcePoller,
} from "@sprinterai/runtime";

// Derive a validation status from source config fields
const status = getSourceValidationStatus(source);
// 'valid' | 'missing-url' | 'invalid-url' | 'missing-credentials' | ...

// Resolve the overall sync status for display
const syncStatus = resolveSourceSyncStatus(source);
// 'active' | 'paused' | 'error' | 'never-run'

// Can a sync run now? (enabled, not already running, not rate-limited)
const canRun = canRunSourceSync(source);

// Is the source due for its next scheduled poll?
const due = isSourceDue(source);

const poller = createSourcePoller({
  store: sourceStore,
  onFetch: async (source) => {
    // Fetch from source.url, return FetchedItem[]
    return items;
  },
  onProcess: async (items, source) => {
    // Process and persist fetched items
  },
});

// Poll a single source
const summary = await poller.pollSource(sourceId);
// { sourceId, itemsFetched, itemsProcessed, durationMs, error? }

// Poll all sources that are currently due
const summaries = await poller.pollAllDueSources(tenantId);