@opengeni/core 0.2.0

package/src/domain/environments.ts

@@ -0,0 +1,115 @@
+import { environmentsEncryptionKeyBytes, type Settings } from "@opengeni/config";
+import type { AccessGrant, WorkspaceEnvironment } from "@opengeni/contracts";
+import {
+  getWorkspaceEnvironment,
+  recordAuditEvent,
+  type Database,
+} from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+import { requirePermission } from "../access";
+
+export const MAX_ENVIRONMENTS_PER_WORKSPACE = 25;
+export const MAX_VARIABLES_PER_ENVIRONMENT = 100;
+
+// Names the platform itself injects into sandboxes (sandboxEnvironmentForRun,
+// collectGitIdentityEnvironment) plus loader/startup-injection vectors. These
+// can never be set as workspace environment variables, so the run-scoped
+// GitHub auth block and git identity always win without silent collisions.
+const reservedExactNames = new Set([
+  "HOME",
+  "PATH",
+  "SHELL",
+  "USER",
+  "LOGNAME",
+  "TMPDIR",
+  "IFS",
+  "ENV",
+  "BASH_ENV",
+  "NODE_OPTIONS",
+  "PYTHONPATH",
+  "PYTHONSTARTUP",
+  "PERL5OPT",
+  "PERL5LIB",
+  "GH_TOKEN",
+  "GITHUB_TOKEN",
+  "GIT_ASKPASS",
+  "GIT_TERMINAL_PROMPT",
+]);
+
+const reservedPrefixes = [
+  "OPENGENI_",
+  "GIT_CONFIG_",
+  "GIT_AUTHOR_",
+  "GIT_COMMITTER_",
+  "LD_",
+  "DYLD_",
+];
+
+export function assertAllowedEnvironmentVariableName(name: string): void {
+  if (reservedExactNames.has(name) || reservedPrefixes.some((prefix) => name.startsWith(prefix))) {
+    throw new HTTPException(422, { message: `reserved environment variable name: ${name}` });
+  }
+}
+
+export function requireEnvironmentEncryption(settings: Settings): Uint8Array {
+  const key = environmentsEncryptionKeyBytes(settings);
+  if (!key) {
+    throw new HTTPException(503, { message: "workspace environments require OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY" });
+  }
+  return key;
+}
+
+export async function requireEnvironmentForApi(db: Database, workspaceId: string, environmentId: string): Promise<WorkspaceEnvironment> {
+  const environment = await getWorkspaceEnvironment(db, workspaceId, environmentId);
+  if (!environment) {
+    throw new HTTPException(404, { message: "environment not found" });
+  }
+  return environment;
+}
+
+/**
+ * Validates an environment attachment supplied in a request payload (session
+ * create, scheduled task create/update, pack enable). Requires the
+ * `environments:use` permission unless the attachment was already authorized
+ * (pack-installation-inherited attachments), and maps a missing or
+ * cross-workspace environment to 422 because the id is payload, not the route
+ * target. RLS plus the workspace_id clause make cross-workspace ids
+ * indistinguishable from missing ones.
+ */
+export async function validateEnvironmentAttachment(
+  deps: { settings: Settings; db: Database },
+  grant: AccessGrant,
+  workspaceId: string,
+  environmentId: string,
+  options: { preauthorized?: boolean } = {},
+): Promise<WorkspaceEnvironment> {
+  requireEnvironmentEncryption(deps.settings);
+  if (!options.preauthorized) {
+    requirePermission(grant, "environments:use");
+  }
+  const environment = await getWorkspaceEnvironment(deps.db, workspaceId, environmentId);
+  if (!environment) {
+    throw new HTTPException(422, { message: "unknown environmentId" });
+  }
+  return environment;
+}
+
+export async function recordEnvironmentAuditEvent(db: Database, input: {
+  grant: AccessGrant;
+  action: "environment.created" | "environment.updated" | "environment.deleted" | "environment.variable.set" | "environment.variable.deleted";
+  environmentId: string;
+  variableName?: string;
+}): Promise<void> {
+  await recordAuditEvent(db, {
+    accountId: input.grant.accountId,
+    workspaceId: input.grant.workspaceId,
+    subjectId: input.grant.subjectId,
+    action: input.action,
+    targetType: "workspace_environment",
+    targetId: input.environmentId,
+    metadata: {
+      environmentId: input.environmentId,
+      ...(input.variableName ? { name: input.variableName } : {}),
+    },
+  });
+}

package/src/domain/packs.ts

@@ -0,0 +1,241 @@
+import {
+  CapabilityPack,
+  type ScheduledTaskAgentConfig,
+  type SocialConnection,
+} from "@opengeni/contracts";
+import { getWorkspacePack, listPackInstallations, listWorkspacePacks, type Database } from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+
+export const MARKETING_SOCIAL_PACK_ID = "marketing-social-daily-analysis";
+
+const marketingSocialPack: CapabilityPack = {
+  id: MARKETING_SOCIAL_PACK_ID,
+  name: "Marketing social daily analysis",
+  description: "Connect social accounts, attach marketing knowledge, and schedule agents to produce daily media performance analysis.",
+  role: "marketing",
+  category: "social-media",
+  version: "0.1.0",
+  // Built-in packs deliberately declare no sandboxImage and no skills: the
+  // worker's pack-runtime resolution only reads manifest-registered packs
+  // (see apps/worker/src/activities/packs.ts), and a test enforces this.
+  skills: [],
+  tools: [
+    { kind: "mcp", id: "opengeni" },
+    { kind: "mcp", id: "docs" },
+  ],
+  connectors: [
+    {
+      id: "x",
+      name: "X",
+      category: "social-media",
+      authModel: "oauth2_authorization_code_pkce",
+      providers: ["x"],
+      scopes: ["tweet.read", "users.read", "offline.access"],
+      required: false,
+      metadata: {
+        docs: "https://docs.x.com/fundamentals/authentication/oauth-2-0/authorization-code",
+      },
+    },
+    {
+      id: "linkedin",
+      name: "LinkedIn",
+      category: "social-media",
+      authModel: "oauth2_authorization_code",
+      providers: ["linkedin"],
+      scopes: ["r_organization_social", "rw_organization_admin"],
+      required: false,
+      metadata: {
+        docs: "https://learn.microsoft.com/en-us/linkedin/marketing/community-management/community-management-overview",
+      },
+    },
+    {
+      id: "instagram",
+      name: "Instagram",
+      category: "social-media",
+      authModel: "oauth2_authorization_code",
+      providers: ["instagram", "facebook"],
+      scopes: ["instagram_basic", "instagram_manage_insights", "pages_read_engagement", "pages_show_list"],
+      required: false,
+      metadata: {
+        docs: "https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/",
+      },
+    },
+    {
+      id: "tiktok",
+      name: "TikTok",
+      category: "social-media",
+      authModel: "oauth2_authorization_code",
+      providers: ["tiktok"],
+      scopes: ["user.info.basic", "video.list"],
+      required: false,
+      metadata: {
+        docs: "https://developers.tiktok.com/doc/tiktok-api-v2-introduction/",
+      },
+    },
+    {
+      id: "youtube",
+      name: "YouTube",
+      category: "social-media",
+      authModel: "oauth2_authorization_code",
+      providers: ["youtube"],
+      scopes: ["https://www.googleapis.com/auth/youtube.readonly", "https://www.googleapis.com/auth/yt-analytics.readonly"],
+      required: false,
+      metadata: {
+        docs: "https://developers.google.com/youtube/v3",
+      },
+    },
+  ],
+  knowledge: [
+    {
+      type: "document_base",
+      id: "marketing-playbook",
+      name: "Marketing playbook",
+      description: "Optional workspace document base with brand voice, campaign calendars, audience research, and reporting rules.",
+      required: false,
+    },
+  ],
+  scheduledTaskTemplates: [
+    {
+      id: "daily-social-analysis",
+      name: "Daily social analysis",
+      description: "Review the latest social posts and account signals every day.",
+      defaultSchedule: {
+        type: "calendar",
+        timeZone: "UTC",
+        hour: 9,
+        minute: 0,
+      },
+      defaultRunMode: "new_session_per_run",
+      defaultOverlapPolicy: "skip",
+    },
+  ],
+  metadata: {
+    skill: "social-media-marketing",
+    firstPartyMcpTools: [
+      "social_connections_list",
+      "social_posts_recent",
+      "social_daily_analysis_context",
+    ],
+  },
+};
+
+const packs = [marketingSocialPack] satisfies CapabilityPack[];
+
+export function listCapabilityPacks(): CapabilityPack[] {
+  return packs;
+}
+
+export function getCapabilityPack(packId: string): CapabilityPack | null {
+  return packs.find((pack) => pack.id === packId) ?? null;
+}
+
+export function isBuiltInCapabilityPack(packId: string): boolean {
+  return getCapabilityPack(packId) !== null;
+}
+
+/**
+ * Built-in packs plus the manifests registered for this workspace. Stored
+ * manifests were validated at registration time; rows that no longer parse
+ * (for example after a contract tightening) are skipped instead of breaking
+ * the whole catalog.
+ */
+export async function listWorkspaceCapabilityPacks(db: Database, workspaceId: string): Promise<CapabilityPack[]> {
+  const registered = await listWorkspacePacks(db, workspaceId);
+  const builtInIds = new Set(packs.map((pack) => pack.id));
+  const registeredPacks = registered
+    .filter((registration) => !builtInIds.has(registration.pack.id))
+    .flatMap((registration) => {
+      const parsed = CapabilityPack.safeParse(registration.pack);
+      return parsed.success ? [parsed.data] : [];
+    });
+  return [...packs, ...registeredPacks];
+}
+
+export async function resolveCapabilityPack(db: Database, workspaceId: string, packId: string): Promise<CapabilityPack | null> {
+  const builtIn = getCapabilityPack(packId);
+  if (builtIn) {
+    return builtIn;
+  }
+  const registration = await getWorkspacePack(db, workspaceId, packId);
+  if (!registration) {
+    return null;
+  }
+  const parsed = CapabilityPack.safeParse(registration.pack);
+  return parsed.success ? parsed.data : null;
+}
+
+/**
+ * v1 pack-scoped runtime rule: at most one enabled pack per workspace may
+ * declare a `sandboxImage` — there is deliberately no image composition or
+ * layering. Enforced when a pack is enabled (both the packs endpoint and the
+ * generic capability enable path) and re-checked at session start by the
+ * worker, which also covers manifests re-registered after enablement.
+ */
+export async function assertPackSandboxImageCompatible(db: Database, workspaceId: string, pack: CapabilityPack): Promise<void> {
+  if (!pack.sandboxImage) {
+    return;
+  }
+  const installations = await listPackInstallations(db, workspaceId);
+  for (const installation of installations) {
+    if (installation.status !== "active" || installation.packId === pack.id) {
+      continue;
+    }
+    const other = await resolveCapabilityPack(db, workspaceId, installation.packId);
+    if (other?.sandboxImage) {
+      throw new HTTPException(409, {
+        message: `pack ${pack.id} declares a sandbox image, but enabled pack ${other.id} already declares one; only one enabled pack per workspace may declare sandboxImage — disable ${other.id} first`,
+      });
+    }
+  }
+}
+
+export function buildMarketingDailyAnalysisAgentConfig(input: {
+  connections: SocialConnection[];
+  documentBaseIds: string[];
+  promptInstructions?: string;
+}): ScheduledTaskAgentConfig {
+  const connectionIds = input.connections.map((connection) => connection.id);
+  return {
+    prompt: marketingDailyAnalysisPrompt({
+      connections: input.connections,
+      documentBaseIds: input.documentBaseIds,
+      ...(input.promptInstructions ? { promptInstructions: input.promptInstructions } : {}),
+    }),
+    resources: [],
+    tools: marketingSocialPack.tools,
+    metadata: {
+      packId: MARKETING_SOCIAL_PACK_ID,
+      packTemplateId: "daily-social-analysis",
+      socialConnectionIds: connectionIds,
+      documentBaseIds: input.documentBaseIds,
+      analysisWindowHours: 24,
+    },
+  };
+}
+
+function marketingDailyAnalysisPrompt(input: {
+  connections: SocialConnection[];
+  documentBaseIds: string[];
+  promptInstructions?: string;
+}): string {
+  const connectionLines = input.connections.map((connection) => {
+    return `- ${connection.provider}: ${connection.accountHandle} (${connection.id})`;
+  }).join("\n");
+  const knowledgeLine = input.documentBaseIds.length > 0
+    ? `Use these document base IDs for brand/campaign knowledge through the docs MCP: ${input.documentBaseIds.join(", ")}.`
+    : "No document base IDs were selected; rely only on social context returned by tools.";
+  const extra = input.promptInstructions ? `\nAdditional operator instructions:\n${input.promptInstructions.trim()}\n` : "";
+
+  return [
+    "Run the daily social media analysis for the selected accounts.",
+    "",
+    "First call the OpenGeni MCP tool social_daily_analysis_context with the selected connection IDs and a 24 hour analysis window. Use social_posts_recent only if you need a narrower follow-up query.",
+    knowledgeLine,
+    "",
+    "Selected accounts:",
+    connectionLines,
+    extra,
+    "Produce a concise report with these sections: executive summary, notable account changes, winning posts, underperforming posts, audience and content signals, recommended actions for the next 24 hours, and data gaps.",
+    "Use only metrics and posts returned by tools or document search. Do not invent metrics, posts, or account capabilities.",
+  ].filter(Boolean).join("\n");
+}

package/src/domain/resources.ts

@@ -0,0 +1,221 @@
+import type { Settings } from "@opengeni/config";
+import {
+  mergeResourceRefs as mergeContractResourceRefs,
+  mergeToolRefs,
+  resourceIdentityKey,
+  ResourceRefConflictError,
+  stableJson,
+  type ResourceRef,
+  type ToolRef,
+} from "@opengeni/contracts";
+import {
+  listGitHubInstallationIdsForWorkspace,
+  requireFile,
+  type Database,
+} from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+
+export function validateToolRefs(tools: ToolRef[], settings: Settings): ToolRef[] {
+  const mcpServerIds = new Set(settings.mcpServers.map((server) => server.id));
+  const selected = new Set<string>();
+  const out: ToolRef[] = [];
+  for (const tool of tools) {
+    if (tool.kind !== "mcp") {
+      throw new HTTPException(422, { message: `unsupported tool kind: ${(tool as { kind?: string }).kind}` });
+    }
+    if (!mcpServerIds.has(tool.id)) {
+      throw new HTTPException(422, { message: `unknown MCP server id: ${tool.id}` });
+    }
+    if (selected.has(tool.id)) {
+      continue;
+    }
+    selected.add(tool.id);
+    // Normalize to a bare, STRICT ref: a client-supplied `optional` flag is
+    // dropped so an EXPLICITLY-requested tool always fails the turn when its
+    // server is unavailable. `optional: true` is set only server-side, at the
+    // default-capability auto-attach seam (enabledCapabilityMcpToolRefs).
+    out.push({ kind: "mcp", id: tool.id });
+  }
+  return out;
+}
+
+type McpSettings = Pick<Settings, "mcpServers">;
+
+export function enabledCapabilityMcpToolRefs(settings: McpSettings, runtimeSettings: McpSettings): ToolRef[] {
+  const configuredIds = new Set(settings.mcpServers.map((server) => server.id));
+  return runtimeSettings.mcpServers
+    .filter((server) => !configuredIds.has(server.id))
+    // AUTO-ATTACHED (workspace-default) capability servers are marked optional:
+    // one of them having a broken/expired credential must SKIP that server, not
+    // fail the whole turn before the model runs. The caller only reaches here
+    // when the request omitted `tools`; an explicit list is never defaulted.
+    .map((server) => ({ kind: "mcp", id: server.id, optional: true }));
+}
+
+export function withDefaultEnabledCapabilityMcpTools(tools: ToolRef[], settings: McpSettings, runtimeSettings: McpSettings): ToolRef[] {
+  return mergeToolRefs(tools, enabledCapabilityMcpToolRefs(settings, runtimeSettings));
+}
+
+export function normalizeResources(resources: ResourceRef[]): ResourceRef[] {
+  const mountPaths = new Map<string, string>();
+  const identities = new Map<string, string>();
+  const seenResources = new Set<string>();
+  const out: ResourceRef[] = [];
+  for (const resource of resources) {
+    let normalized: ResourceRef;
+    if (resource.kind === "file") {
+      const mountPath = normalizeMountPath(resource.mountPath ?? `files/${resource.fileId}`);
+      normalized = {
+        kind: "file",
+        fileId: resource.fileId,
+        mountPath,
+      };
+    } else {
+      const url = parseResourceUrl(resource.uri);
+      if (url.protocol !== "https:" || !url.hostname) {
+        throw new HTTPException(422, { message: "repository resources must use HTTPS Git URLs" });
+      }
+      const path = url.pathname.replace(/^\/+|\/+$/g, "").replace(/\.git$/, "");
+      const parts = path.split("/").filter(Boolean);
+      if (parts.length < 2) {
+        throw new HTTPException(422, { message: "repository URL must include owner and repo" });
+      }
+      const repo = parts.join("/");
+      const mountPath = normalizeMountPath(resource.mountPath ?? `repos/${repo}`);
+      normalized = {
+        kind: "repository",
+        uri: `https://${url.hostname.toLowerCase()}/${repo}.git`,
+        ref: resource.ref.trim(),
+        mountPath,
+        ...(resource.subpath ? { subpath: normalizeMountPath(resource.subpath) } : {}),
+        ...(resource.githubInstallationId ? { githubInstallationId: resource.githubInstallationId } : {}),
+        ...(resource.githubRepositoryId ? { githubRepositoryId: resource.githubRepositoryId } : {}),
+      };
+    }
+    const key = stableJson(normalized);
+    const mounted = normalized.mountPath ? mountPaths.get(normalized.mountPath) : undefined;
+    if (mounted && mounted !== key) {
+      throw new HTTPException(422, { message: `duplicate resource mount path: ${normalized.mountPath}` });
+    }
+    if (normalized.mountPath) {
+      mountPaths.set(normalized.mountPath, key);
+    }
+    const identity = resourceIdentityKey(normalized);
+    const seenIdentity = identities.get(identity);
+    if (seenIdentity && seenIdentity !== key) {
+      throw new HTTPException(422, { message: `duplicate resource with different settings: ${identity}` });
+    }
+    identities.set(identity, key);
+    if (!seenResources.has(key)) {
+      seenResources.add(key);
+      out.push(normalized);
+    }
+  }
+  return out;
+}
+
+export function mergeResourceRefs(existing: ResourceRef[], additions: ResourceRef[]): ResourceRef[] {
+  try {
+    return mergeContractResourceRefs(existing, additions, { rejectConflicts: true });
+  } catch (error) {
+    if (error instanceof ResourceRefConflictError) {
+      throw new HTTPException(422, { message: error.message });
+    }
+    throw error;
+  }
+}
+
+export function validateGitHubRepositorySelectionShape(resources: ResourceRef[]): number | null {
+  const selected = resources.flatMap((resource) => {
+    if (resource.kind !== "repository") {
+      return [];
+    }
+    const installationRaw = resource.githubInstallationId;
+    const repositoryRaw = resource.githubRepositoryId;
+    if (installationRaw === null && repositoryRaw === null) {
+      return [];
+    }
+    if (installationRaw === undefined && repositoryRaw === undefined) {
+      return [];
+    }
+    const installationId = positiveInteger(installationRaw);
+    const repositoryId = positiveInteger(repositoryRaw);
+    if (!installationId || !repositoryId) {
+      throw new HTTPException(422, {
+        message: "GitHub App repository resources require positive github_installation_id and github_repository_id",
+      });
+    }
+    return [{ installationId, repositoryId }];
+  });
+  if (selected.length === 0) {
+    return null;
+  }
+  const installationId = selected[0]!.installationId;
+  if (selected.some((item) => item.installationId !== installationId)) {
+    throw new HTTPException(422, {
+      message: "GitHub App repository resources must belong to one installation",
+    });
+  }
+  return installationId;
+}
+
+export async function validateGitHubRepositorySelection(db: Database, workspaceId: string, resources: ResourceRef[]): Promise<void> {
+  const installationId = validateGitHubRepositorySelectionShape(resources);
+  if (installationId === null) {
+    return;
+  }
+  const linkedInstallationIds = new Set(await listGitHubInstallationIdsForWorkspace(db, workspaceId));
+  if (!linkedInstallationIds.has(installationId)) {
+    throw new HTTPException(422, {
+      message: "GitHub App repository resources must belong to a GitHub App installation linked to this workspace",
+    });
+  }
+}
+
+export async function validateFileResources(db: Database, workspaceId: string, resources: ResourceRef[]): Promise<void> {
+  const fileIds = new Set<string>();
+  for (const resource of resources) {
+    if (resource.kind !== "file") {
+      continue;
+    }
+    if (fileIds.has(resource.fileId)) {
+      throw new HTTPException(422, { message: `duplicate file resource: ${resource.fileId}` });
+    }
+    fileIds.add(resource.fileId);
+    const file = await requireFile(db, workspaceId, resource.fileId).catch(() => null);
+    if (!file) {
+      throw new HTTPException(422, { message: `unknown file resource: ${resource.fileId}` });
+    }
+    if (file.status !== "ready") {
+      throw new HTTPException(422, { message: `file resource ${resource.fileId} is ${file.status}` });
+    }
+  }
+}
+
+function normalizeMountPath(path: string): string {
+  const normalized = path.trim().replace(/^\/+|\/+$/g, "");
+  if (!normalized || normalized.includes("..")) {
+    throw new HTTPException(422, { message: `invalid resource mount path: ${path}` });
+  }
+  return normalized;
+}
+
+function parseResourceUrl(uri: string): URL {
+  try {
+    return new URL(uri);
+  } catch {
+    throw new HTTPException(422, { message: "repository resources must use valid URLs" });
+  }
+}
+
+function positiveInteger(value: unknown): number | null {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+    return value;
+  }
+  if (typeof value === "string" && /^\d+$/.test(value) && Number(value) > 0) {
+    return Number(value);
+  }
+  return null;
+}
+
+export { mergeToolRefs, stableJson };