@hotmeshio/long-tail 0.12.1 → 0.13.1

package/README.md

@@ -230,6 +230,7 @@ All modes share PostgreSQL and scale independently. See [Cloud Deployment](https
 | [CLI](https://github.com/hotmeshio/long-tail/blob/main/docs/cli.md) | `ltc` — terminal access to workflows, escalations, knowledge, MCP |
 | [Escalation Strategies](https://github.com/hotmeshio/long-tail/blob/main/docs/escalation-strategies.md) | Default, MCP triage, custom handlers |
 | [Schema Enforcement](https://github.com/hotmeshio/long-tail/blob/main/docs/schema-enforcement.md) | form_schema as an enforced API contract on every resolve surface |
+| [Code-Owned Configuration](https://github.com/hotmeshio/long-tail/blob/main/docs/code-owned-configuration.md) | `configSource` — declared config compared and applied at every boot |
 | [Faceted Routing](https://github.com/hotmeshio/long-tail/blob/main/docs/faceted-routing.md) | Query and atomically claim the queue by facets; dispatcher pattern |
 | [SDK](https://github.com/hotmeshio/long-tail/blob/main/docs/sdk.md) | Embedded usage, `createClient`, event subscriptions |
 | [Architecture](https://github.com/hotmeshio/long-tail/blob/main/docs/architecture.md) | Project structure, conventions, discovery |

package/build/api/auth-sso.d.ts

@@ -1,12 +1,15 @@
-import type { Request } from 'express';
+import type { Request, Response } from 'express';
 import type { LTApiResult } from '../types/sdk';
 /**
  * Exchange host authentication for a Long Tail JWT.
  *
- * Calls `sso.resolve(req)` to extract the host identity, JIT provisions
+ * Calls `sso.resolve(req, res)` to extract the host identity, JIT provisions
  * the user in `lt_users`, and returns a signed JWT the dashboard can
  * store for subsequent API calls.
  *
  * No request body required — the host's cookies/headers carry the auth.
+ * `res` gives cookie-owning hosts the response handle at the exchange
+ * boundary (login and every keepalive beat) to set/refresh their session
+ * cookie — headers only; the route writes the response body.
  */
-export declare function exchangeSSO(req: Request): Promise<LTApiResult>;
+export declare function exchangeSSO(req: Request, res?: Response): Promise<LTApiResult>;

package/build/api/auth-sso.js

@@ -7,19 +7,22 @@ const auth_1 = require("../modules/auth");
 /**
  * Exchange host authentication for a Long Tail JWT.
  *
- * Calls `sso.resolve(req)` to extract the host identity, JIT provisions
+ * Calls `sso.resolve(req, res)` to extract the host identity, JIT provisions
  * the user in `lt_users`, and returns a signed JWT the dashboard can
  * store for subsequent API calls.
  *
  * No request body required — the host's cookies/headers carry the auth.
+ * `res` gives cookie-owning hosts the response handle at the exchange
+ * boundary (login and every keepalive beat) to set/refresh their session
+ * cookie — headers only; the route writes the response body.
  */
-async function exchangeSSO(req) {
+async function exchangeSSO(req, res) {
     try {
         const ssoConfig = (0, sso_1.getSSOConfig)();
         if (!ssoConfig) {
             return { status: 404, error: 'SSO not configured' };
         }
-        const identity = await ssoConfig.resolve(req);
+        const identity = await ssoConfig.resolve(req, res);
         if (!identity) {
             return { status: 401, error: 'Host authentication required' };
         }

package/build/api/escalations/helpers.js

@@ -245,9 +245,11 @@ async function ensureRoleMembership(userId, requiredRole, callerUserId, provisio
     const declaredRole = provisionIfAbsent.roles?.find((r) => r.role === requiredRole);
     if (!declaredRole)
         return false;
-    // Add the role — idempotent (ON CONFLICT DO NOTHING)
+    // Add the role only when ABSENT (ON CONFLICT DO NOTHING). Provisioning is a
+    // sync of membership, never of scope: a grant the admin already restricted
+    // (e.g. write:none on a station) must survive every claim-time provision.
     try {
-        await userService.addUserRole(userId, requiredRole, (declaredRole.type || 'member'), {
+        await userService.grantRoleIfAbsent(userId, requiredRole, (declaredRole.type || 'member'), {
             read_scope: declaredRole.read_scope,
             write_scope: declaredRole.write_scope,
         });

package/build/api/settings.js

@@ -68,6 +68,9 @@ async function getSettings(req) {
                 auth: {
                     sso: (0, sso_1.isSSOEnabled)(),
                     ssoLogoutUrl: (0, sso_1.getSSOConfig)()?.logoutUrl ?? null,
+                    // Session keepalive dials for the SPA (null = no keepalive / no idle gate).
+                    ssoKeepaliveSeconds: (0, sso_1.getSSOConfig)()?.keepaliveSeconds ?? null,
+                    ssoKeepaliveIdleTimeoutSeconds: (0, sso_1.getSSOConfig)()?.keepaliveIdleTimeoutSeconds ?? null,
                 },
                 ai: {
                     enabled: (0, llm_1.hasLLMApiKey)(),

package/build/modules/auth.js

@@ -43,6 +43,7 @@ exports.signToken = signToken;
 const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
 const config_1 = require("./config");
 const sso_1 = require("./sso");
+const logger_1 = require("../lib/logger");
 const user_1 = require("../services/user");
 const sso_provision_1 = require("../services/user/sso-provision");
 const bot_api_key_1 = require("../services/auth/bot-api-key");
@@ -156,7 +157,10 @@ const requireAuth = async (req, res, next) => {
         const mw = _authMiddleware || createAuthMiddleware(new JwtAuthAdapter());
         return mw(req, res, next);
     }
-    // SSO fallback: no Bearer, but host may have authenticated via cookies/headers
+    // SSO fallback: no Bearer, but host may have authenticated via cookies/headers.
+    // `res` is deliberately NOT passed to resolve here: this path runs on every
+    // cookie-bearing request, and ambient API traffic must never slide the host
+    // session — only the explicit exchange (login + gated keepalive beat) does.
     const ssoConfig = (0, sso_1.getSSOConfig)();
     if (ssoConfig) {
         try {
@@ -177,8 +181,10 @@ const requireAuth = async (req, res, next) => {
                 return next();
             }
         }
-        catch {
-            // SSO resolve failed — fall through to 401
+        catch (err) {
+            // SSO resolve failed — fall through to 401, but leave a trace so host
+            // resolve errors are diagnosable.
+            logger_1.loggerRegistry.debug(`[long-tail] sso resolve failed on auth fallback: ${err?.message}`);
         }
     }
     // No Bearer, no SSO — delegate to standard middleware (returns 401)

package/build/routes/auth-sso.js

@@ -45,7 +45,12 @@ const router = (0, express_1.Router)();
  * login form with a transparent token exchange.
  */
 router.post('/sso', async (req, res) => {
-    const result = await api.exchangeSSO(req);
+    const result = await api.exchangeSSO(req, res);
+    // A host's resolve may only set headers on `res`; if one violates the
+    // contract and writes the response, degrade to a skipped beat instead of
+    // a headers-after-send crash.
+    if (res.headersSent)
+        return;
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 exports.default = router;

package/build/services/agent/index.d.ts

@@ -9,6 +9,8 @@ export declare function listAgents(filters?: ListAgentsFilters): Promise<{
     agents: LTAgent[];
     total: number;
 }>;
+/** Every agent id — the startup orphan report's candidate set. */
+export declare function listAgentIds(): Promise<string[]>;
 export declare function getAgent(id: string): Promise<LTAgent | null>;
 export declare function createAgent(data: Partial<LTAgent> & {
     id: string;
@@ -23,6 +25,15 @@ export declare function deleteAgent(id: string): Promise<boolean>;
 export declare function seedAgent(data: Partial<LTAgent> & {
     id: string;
 }): Promise<boolean>;
+/**
+ * Apply an agent declaration at startup (code is source of truth).
+ * Declared fields — description, status, knowledge domain, behaviors, goals,
+ * rules, reaction targets — are written when they differ; runtime state
+ * (user_id, capabilities, metadata, last_run_at) is never touched.
+ */
+export declare function applyAgent(data: Partial<LTAgent> & {
+    id: string;
+}): Promise<'applied' | 'unchanged'>;
 /**
  * Aggregate stats for an agent: knowledge entry count, pending escalation count,
  * and last workflow execution time.

package/build/services/agent/index.js

@@ -34,11 +34,13 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listAgents = listAgents;
+exports.listAgentIds = listAgentIds;
 exports.getAgent = getAgent;
 exports.createAgent = createAgent;
 exports.updateAgent = updateAgent;
 exports.deleteAgent = deleteAgent;
 exports.seedAgent = seedAgent;
+exports.applyAgent = applyAgent;
 exports.getAgentStats = getAgentStats;
 const db_1 = require("../../lib/db");
 const logger_1 = require("../../lib/logger");
@@ -59,6 +61,12 @@ async function listAgents(filters = {}) {
         total: countRes.rows[0]?.total ?? 0,
     };
 }
+/** Every agent id — the startup orphan report's candidate set. */
+async function listAgentIds() {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.LIST_AGENT_IDS);
+    return rows.map((r) => r.id);
+}
 async function getAgent(id) {
     const pool = (0, db_1.getPool)();
     const { rows } = await pool.query(sql_1.GET_AGENT, [id]);
@@ -179,6 +187,30 @@ async function seedAgent(data) {
     }
     return inserted;
 }
+/**
+ * Apply an agent declaration at startup (code is source of truth).
+ * Declared fields — description, status, knowledge domain, behaviors, goals,
+ * rules, reaction targets — are written when they differ; runtime state
+ * (user_id, capabilities, metadata, last_run_at) is never touched.
+ */
+async function applyAgent(data) {
+    const pool = (0, db_1.getPool)();
+    const { rowCount } = await pool.query(sql_1.APPLY_AGENT, [
+        data.id,
+        data.description ?? null,
+        data.status ?? 'inactive',
+        data.user_id ?? null,
+        data.knowledge_domain ?? null,
+        JSON.stringify(data.capabilities ?? []),
+        JSON.stringify(data.behaviors ?? {}),
+        data.goals ?? null,
+        data.rules ?? null,
+        data.workflow_type ?? null,
+        data.pipeline_id ?? null,
+        JSON.stringify(data.metadata ?? {}),
+    ]);
+    return (rowCount ?? 0) > 0 ? 'applied' : 'unchanged';
+}
 /**
  * Aggregate stats for an agent: knowledge entry count, pending escalation count,
  * and last workflow execution time.

package/build/services/agent/sql.d.ts

@@ -1,9 +1,16 @@
 export declare const LIST_AGENTS = "\n  SELECT a.*,\n    COALESCE(s.sub_count, 0)::int AS subscription_count,\n    s.sub_topics\n  FROM lt_agents a\n  LEFT JOIN LATERAL (\n    SELECT COUNT(*)::int AS sub_count,\n           array_agg(topic ORDER BY created_at) AS sub_topics\n    FROM lt_agent_subscriptions\n    WHERE agent_id = a.id AND enabled = true\n  ) s ON true\n  WHERE ($1::text IS NULL OR a.status = $1)\n    AND ($2::text IS NULL OR a.knowledge_domain = $2)\n  ORDER BY a.updated_at DESC\n  LIMIT $3 OFFSET $4\n";
 export declare const COUNT_AGENTS = "\n  SELECT COUNT(*)::int AS total FROM lt_agents\n  WHERE ($1::text IS NULL OR status = $1)\n    AND ($2::text IS NULL OR knowledge_domain = $2)\n";
 export declare const GET_AGENT = "\n  SELECT * FROM lt_agents WHERE id = $1\n";
+export declare const LIST_AGENT_IDS = "\n  SELECT id FROM lt_agents ORDER BY id\n";
 export declare const INSERT_AGENT = "\n  INSERT INTO lt_agents (id, description, status, user_id, knowledge_domain,\n    capabilities, behaviors, goals, rules, workflow_type, pipeline_id, metadata)\n  VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)\n  RETURNING *\n";
 export declare const UPDATE_AGENT = "\n  UPDATE lt_agents SET\n    description = COALESCE($2, description),\n    status = COALESCE($3, status),\n    user_id = COALESCE($4, user_id),\n    knowledge_domain = COALESCE($5, knowledge_domain),\n    capabilities = COALESCE($6, capabilities),\n    behaviors = COALESCE($7, behaviors),\n    goals = COALESCE($8, goals),\n    rules = COALESCE($9, rules),\n    workflow_type = COALESCE($10, workflow_type),\n    pipeline_id = COALESCE($11, pipeline_id),\n    metadata = COALESCE($12, metadata),\n    last_run_at = COALESCE($13, last_run_at)\n  WHERE id = $1\n  RETURNING *\n";
 export declare const DELETE_AGENT = "\n  DELETE FROM lt_agents WHERE id = $1\n";
 export declare const SEED_AGENT = "\n  INSERT INTO lt_agents (id, description, status, user_id, knowledge_domain,\n    capabilities, behaviors, goals, rules, workflow_type, pipeline_id, metadata)\n  VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)\n  ON CONFLICT (id) DO NOTHING\n";
+/**
+ * Apply — code is source of truth for the declared fields. Runtime state
+ * (user_id, capabilities, metadata, last_run_at) is never touched; the
+ * IS DISTINCT FROM guard makes an unchanged declaration a zero-row no-op.
+ */
+export declare const APPLY_AGENT = "\n  INSERT INTO lt_agents (id, description, status, user_id, knowledge_domain,\n    capabilities, behaviors, goals, rules, workflow_type, pipeline_id, metadata)\n  VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)\n  ON CONFLICT (id) DO UPDATE SET\n    description = EXCLUDED.description,\n    status = EXCLUDED.status,\n    knowledge_domain = EXCLUDED.knowledge_domain,\n    behaviors = EXCLUDED.behaviors,\n    goals = EXCLUDED.goals,\n    rules = EXCLUDED.rules,\n    workflow_type = EXCLUDED.workflow_type,\n    pipeline_id = EXCLUDED.pipeline_id,\n    updated_at = NOW()\n  WHERE (lt_agents.description, lt_agents.status, lt_agents.knowledge_domain,\n         lt_agents.behaviors, lt_agents.goals, lt_agents.rules,\n         lt_agents.workflow_type, lt_agents.pipeline_id)\n    IS DISTINCT FROM\n        (EXCLUDED.description, EXCLUDED.status, EXCLUDED.knowledge_domain,\n         EXCLUDED.behaviors, EXCLUDED.goals, EXCLUDED.rules,\n         EXCLUDED.workflow_type, EXCLUDED.pipeline_id)\n  RETURNING (xmax = 0) AS inserted\n";
 export declare const KNOWLEDGE_COUNT = "\n  SELECT COUNT(*)::int AS count FROM lt_knowledge WHERE domain = $1\n";
 export declare const ESCALATION_COUNT = "\n  SELECT COUNT(*)::int AS count FROM lt_escalations\n  WHERE status = 'pending' AND created_by = $1\n";

package/build/services/agent/sql.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ESCALATION_COUNT = exports.KNOWLEDGE_COUNT = exports.SEED_AGENT = exports.DELETE_AGENT = exports.UPDATE_AGENT = exports.INSERT_AGENT = exports.GET_AGENT = exports.COUNT_AGENTS = exports.LIST_AGENTS = void 0;
+exports.ESCALATION_COUNT = exports.KNOWLEDGE_COUNT = exports.APPLY_AGENT = exports.SEED_AGENT = exports.DELETE_AGENT = exports.UPDATE_AGENT = exports.INSERT_AGENT = exports.LIST_AGENT_IDS = exports.GET_AGENT = exports.COUNT_AGENTS = exports.LIST_AGENTS = void 0;
 exports.LIST_AGENTS = `
   SELECT a.*,
     COALESCE(s.sub_count, 0)::int AS subscription_count,
@@ -25,6 +25,9 @@ exports.COUNT_AGENTS = `
 exports.GET_AGENT = `
   SELECT * FROM lt_agents WHERE id = $1
 `;
+exports.LIST_AGENT_IDS = `
+  SELECT id FROM lt_agents ORDER BY id
+`;
 exports.INSERT_AGENT = `
   INSERT INTO lt_agents (id, description, status, user_id, knowledge_domain,
     capabilities, behaviors, goals, rules, workflow_type, pipeline_id, metadata)
@@ -57,6 +60,34 @@ exports.SEED_AGENT = `
   VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
   ON CONFLICT (id) DO NOTHING
 `;
+/**
+ * Apply — code is source of truth for the declared fields. Runtime state
+ * (user_id, capabilities, metadata, last_run_at) is never touched; the
+ * IS DISTINCT FROM guard makes an unchanged declaration a zero-row no-op.
+ */
+exports.APPLY_AGENT = `
+  INSERT INTO lt_agents (id, description, status, user_id, knowledge_domain,
+    capabilities, behaviors, goals, rules, workflow_type, pipeline_id, metadata)
+  VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+  ON CONFLICT (id) DO UPDATE SET
+    description = EXCLUDED.description,
+    status = EXCLUDED.status,
+    knowledge_domain = EXCLUDED.knowledge_domain,
+    behaviors = EXCLUDED.behaviors,
+    goals = EXCLUDED.goals,
+    rules = EXCLUDED.rules,
+    workflow_type = EXCLUDED.workflow_type,
+    pipeline_id = EXCLUDED.pipeline_id,
+    updated_at = NOW()
+  WHERE (lt_agents.description, lt_agents.status, lt_agents.knowledge_domain,
+         lt_agents.behaviors, lt_agents.goals, lt_agents.rules,
+         lt_agents.workflow_type, lt_agents.pipeline_id)
+    IS DISTINCT FROM
+        (EXCLUDED.description, EXCLUDED.status, EXCLUDED.knowledge_domain,
+         EXCLUDED.behaviors, EXCLUDED.goals, EXCLUDED.rules,
+         EXCLUDED.workflow_type, EXCLUDED.pipeline_id)
+  RETURNING (xmax = 0) AS inserted
+`;
 exports.KNOWLEDGE_COUNT = `
   SELECT COUNT(*)::int AS count FROM lt_knowledge WHERE domain = $1
 `;

package/build/services/agent/subscription-sql.d.ts

@@ -4,4 +4,10 @@ export declare const INSERT_SUBSCRIPTION = "\n  INSERT INTO lt_agent_subscriptio
 export declare const UPDATE_SUBSCRIPTION = "\n  UPDATE lt_agent_subscriptions SET\n    topic = COALESCE($2, topic),\n    filter = COALESCE($3, filter),\n    reaction_type = COALESCE($4, reaction_type),\n    workflow_type = COALESCE($5, workflow_type),\n    pipeline_id = COALESCE($6, pipeline_id),\n    mcp_prompt = COALESCE($7, mcp_prompt),\n    input_mapping = COALESCE($8, input_mapping),\n    execute_as = COALESCE($9, execute_as),\n    enabled = COALESCE($10, enabled),\n    server_id = COALESCE($11, server_id),\n    tool_name = COALESCE($12, tool_name)\n  WHERE id = $1\n  RETURNING *\n";
 export declare const DELETE_SUBSCRIPTION = "\n  DELETE FROM lt_agent_subscriptions WHERE id = $1\n";
 export declare const SEED_SUBSCRIPTION = "\n  INSERT INTO lt_agent_subscriptions\n    (agent_id, topic, filter, reaction_type, workflow_type, pipeline_id, mcp_prompt,\n     input_mapping, execute_as, enabled, server_id, tool_name)\n  VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, true, $10, $11)\n  ON CONFLICT (agent_id, topic) DO NOTHING\n";
+/**
+ * Apply — code is source of truth for the reaction fields. `enabled` is left
+ * alone on update (an admin kill-switch stays honored); the IS DISTINCT FROM
+ * guard makes an unchanged declaration a zero-row no-op.
+ */
+export declare const APPLY_SUBSCRIPTION = "\n  INSERT INTO lt_agent_subscriptions\n    (agent_id, topic, filter, reaction_type, workflow_type, pipeline_id, mcp_prompt,\n     input_mapping, execute_as, enabled, server_id, tool_name)\n  VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, true, $10, $11)\n  ON CONFLICT (agent_id, topic) DO UPDATE SET\n    filter = EXCLUDED.filter,\n    reaction_type = EXCLUDED.reaction_type,\n    workflow_type = EXCLUDED.workflow_type,\n    pipeline_id = EXCLUDED.pipeline_id,\n    mcp_prompt = EXCLUDED.mcp_prompt,\n    input_mapping = EXCLUDED.input_mapping,\n    execute_as = EXCLUDED.execute_as,\n    server_id = EXCLUDED.server_id,\n    tool_name = EXCLUDED.tool_name\n  WHERE (lt_agent_subscriptions.filter, lt_agent_subscriptions.reaction_type,\n         lt_agent_subscriptions.workflow_type, lt_agent_subscriptions.pipeline_id,\n         lt_agent_subscriptions.mcp_prompt, lt_agent_subscriptions.input_mapping,\n         lt_agent_subscriptions.execute_as, lt_agent_subscriptions.server_id,\n         lt_agent_subscriptions.tool_name)\n    IS DISTINCT FROM\n        (EXCLUDED.filter, EXCLUDED.reaction_type, EXCLUDED.workflow_type,\n         EXCLUDED.pipeline_id, EXCLUDED.mcp_prompt, EXCLUDED.input_mapping,\n         EXCLUDED.execute_as, EXCLUDED.server_id, EXCLUDED.tool_name)\n  RETURNING (xmax = 0) AS inserted\n";
 export declare const LIST_ACTIVE_SUBSCRIPTIONS = "\n  SELECT s.*, a.id AS agent_name, a.user_id AS agent_user_id\n  FROM lt_agent_subscriptions s\n  JOIN lt_agents a ON s.agent_id = a.id\n  WHERE s.enabled = true AND a.status = 'active'\n  ORDER BY s.created_at\n";

package/build/services/agent/subscription-sql.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LIST_ACTIVE_SUBSCRIPTIONS = exports.SEED_SUBSCRIPTION = exports.DELETE_SUBSCRIPTION = exports.UPDATE_SUBSCRIPTION = exports.INSERT_SUBSCRIPTION = exports.GET_SUBSCRIPTION = exports.LIST_SUBSCRIPTIONS = void 0;
+exports.LIST_ACTIVE_SUBSCRIPTIONS = exports.APPLY_SUBSCRIPTION = exports.SEED_SUBSCRIPTION = exports.DELETE_SUBSCRIPTION = exports.UPDATE_SUBSCRIPTION = exports.INSERT_SUBSCRIPTION = exports.GET_SUBSCRIPTION = exports.LIST_SUBSCRIPTIONS = void 0;
 exports.LIST_SUBSCRIPTIONS = `
   SELECT * FROM lt_agent_subscriptions
   WHERE agent_id = $1
@@ -42,6 +42,37 @@ exports.SEED_SUBSCRIPTION = `
   VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, true, $10, $11)
   ON CONFLICT (agent_id, topic) DO NOTHING
 `;
+/**
+ * Apply — code is source of truth for the reaction fields. `enabled` is left
+ * alone on update (an admin kill-switch stays honored); the IS DISTINCT FROM
+ * guard makes an unchanged declaration a zero-row no-op.
+ */
+exports.APPLY_SUBSCRIPTION = `
+  INSERT INTO lt_agent_subscriptions
+    (agent_id, topic, filter, reaction_type, workflow_type, pipeline_id, mcp_prompt,
+     input_mapping, execute_as, enabled, server_id, tool_name)
+  VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, true, $10, $11)
+  ON CONFLICT (agent_id, topic) DO UPDATE SET
+    filter = EXCLUDED.filter,
+    reaction_type = EXCLUDED.reaction_type,
+    workflow_type = EXCLUDED.workflow_type,
+    pipeline_id = EXCLUDED.pipeline_id,
+    mcp_prompt = EXCLUDED.mcp_prompt,
+    input_mapping = EXCLUDED.input_mapping,
+    execute_as = EXCLUDED.execute_as,
+    server_id = EXCLUDED.server_id,
+    tool_name = EXCLUDED.tool_name
+  WHERE (lt_agent_subscriptions.filter, lt_agent_subscriptions.reaction_type,
+         lt_agent_subscriptions.workflow_type, lt_agent_subscriptions.pipeline_id,
+         lt_agent_subscriptions.mcp_prompt, lt_agent_subscriptions.input_mapping,
+         lt_agent_subscriptions.execute_as, lt_agent_subscriptions.server_id,
+         lt_agent_subscriptions.tool_name)
+    IS DISTINCT FROM
+        (EXCLUDED.filter, EXCLUDED.reaction_type, EXCLUDED.workflow_type,
+         EXCLUDED.pipeline_id, EXCLUDED.mcp_prompt, EXCLUDED.input_mapping,
+         EXCLUDED.execute_as, EXCLUDED.server_id, EXCLUDED.tool_name)
+  RETURNING (xmax = 0) AS inserted
+`;
 exports.LIST_ACTIVE_SUBSCRIPTIONS = `
   SELECT s.*, a.id AS agent_name, a.user_id AS agent_user_id
   FROM lt_agent_subscriptions s

package/build/services/agent/subscriptions.d.ts

@@ -30,3 +30,9 @@ export declare function listActiveSubscriptions(): Promise<ActiveSubscription[]>
  * Conflict on (agent_id, topic) — DB is source of truth after first boot.
  */
 export declare function seedSubscription(agentId: string, data: Partial<AgentSubscription>): Promise<boolean>;
+/**
+ * Apply a subscription declaration at startup (code is source of truth).
+ * Reaction fields are written when they differ; `enabled` is honored as an
+ * admin kill-switch and never flipped on update.
+ */
+export declare function applySubscription(agentId: string, data: Partial<AgentSubscription>): Promise<'applied' | 'unchanged'>;

package/build/services/agent/subscriptions.js

@@ -7,6 +7,7 @@ exports.updateSubscription = updateSubscription;
 exports.deleteSubscription = deleteSubscription;
 exports.listActiveSubscriptions = listActiveSubscriptions;
 exports.seedSubscription = seedSubscription;
+exports.applySubscription = applySubscription;
 const db_1 = require("../../lib/db");
 const subscription_sql_1 = require("./subscription-sql");
 async function listSubscriptions(agentId) {
@@ -86,3 +87,25 @@ async function seedSubscription(agentId, data) {
     ]);
     return (rowCount ?? 0) > 0;
 }
+/**
+ * Apply a subscription declaration at startup (code is source of truth).
+ * Reaction fields are written when they differ; `enabled` is honored as an
+ * admin kill-switch and never flipped on update.
+ */
+async function applySubscription(agentId, data) {
+    const pool = (0, db_1.getPool)();
+    const { rowCount } = await pool.query(subscription_sql_1.APPLY_SUBSCRIPTION, [
+        agentId,
+        data.topic,
+        data.filter ? JSON.stringify(data.filter) : null,
+        data.reaction_type,
+        data.workflow_type ?? null,
+        data.pipeline_id ?? null,
+        data.mcp_prompt ?? null,
+        JSON.stringify(data.input_mapping ?? {}),
+        data.execute_as ?? null,
+        data.server_id ?? null,
+        data.tool_name ?? null,
+    ]);
+    return (rowCount ?? 0) > 0 ? 'applied' : 'unchanged';
+}

package/build/services/config/index.d.ts

@@ -1,4 +1,4 @@
 export { getWorkflowConfig, listWorkflowConfigs } from './read';
-export { upsertWorkflowConfig, deleteWorkflowConfig } from './write';
+export { upsertWorkflowConfig, deleteWorkflowConfig, applyWorkflowConfig } from './write';
 export { loadAllConfigs } from './cache';
 export { getProviderData } from './provider';

package/build/services/config/index.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getProviderData = exports.loadAllConfigs = exports.deleteWorkflowConfig = exports.upsertWorkflowConfig = exports.listWorkflowConfigs = exports.getWorkflowConfig = void 0;
+exports.getProviderData = exports.loadAllConfigs = exports.applyWorkflowConfig = exports.deleteWorkflowConfig = exports.upsertWorkflowConfig = exports.listWorkflowConfigs = exports.getWorkflowConfig = void 0;
 var read_1 = require("./read");
 Object.defineProperty(exports, "getWorkflowConfig", { enumerable: true, get: function () { return read_1.getWorkflowConfig; } });
 Object.defineProperty(exports, "listWorkflowConfigs", { enumerable: true, get: function () { return read_1.listWorkflowConfigs; } });
 var write_1 = require("./write");
 Object.defineProperty(exports, "upsertWorkflowConfig", { enumerable: true, get: function () { return write_1.upsertWorkflowConfig; } });
 Object.defineProperty(exports, "deleteWorkflowConfig", { enumerable: true, get: function () { return write_1.deleteWorkflowConfig; } });
+Object.defineProperty(exports, "applyWorkflowConfig", { enumerable: true, get: function () { return write_1.applyWorkflowConfig; } });
 var cache_1 = require("./cache");
 Object.defineProperty(exports, "loadAllConfigs", { enumerable: true, get: function () { return cache_1.loadAllConfigs; } });
 var provider_1 = require("./provider");

package/build/services/config/write.d.ts

@@ -9,3 +9,13 @@ export declare function deleteWorkflowConfig(workflowType: string): Promise<bool
  * but do not overwrite. Returns true if inserted, false if already existed.
  */
 export declare function seedWorkflowConfig(config: LTWorkflowConfig): Promise<boolean>;
+/**
+ * Apply a workflow config at startup (code is source of truth).
+ *
+ * The declared config is diffed against the stored row — jsonb fields as
+ * parsed values, role lists order-insensitively — and written through the
+ * same full-replace transaction the admin surface uses only when something
+ * actually differs. `certified` is explicit-only on this path: an omitted
+ * flag registers the workflow as NOT certified.
+ */
+export declare function applyWorkflowConfig(config: LTWorkflowConfig): Promise<'applied' | 'unchanged'>;

package/build/services/config/write.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.upsertWorkflowConfig = upsertWorkflowConfig;
 exports.deleteWorkflowConfig = deleteWorkflowConfig;
 exports.seedWorkflowConfig = seedWorkflowConfig;
+exports.applyWorkflowConfig = applyWorkflowConfig;
+const node_util_1 = require("node:util");
 const db_1 = require("../../lib/db");
 const read_1 = require("./read");
 const logger_1 = require("../../lib/logger");
@@ -16,7 +18,13 @@ function resolveCertified(config) {
     return (config.certified ??
         ((config.roles?.length ?? 0) > 0 || (config.consumes?.length ?? 0) > 0));
 }
-async function upsertWorkflowConfig(config) {
+/**
+ * Full replace of one workflow config in a single transaction: FK role
+ * ensures, the workflow row upsert, and replace semantics for the roles and
+ * invocation-roles side tables. Both the admin upsert and the startup apply
+ * write through here — they differ only in how `certified` resolves.
+ */
+async function replaceWorkflowConfig(config, certified) {
     const pool = (0, db_1.getPool)();
     const client = await pool.connect();
     try {
@@ -43,7 +51,7 @@ async function upsertWorkflowConfig(config) {
             config.cron_schedule ?? null,
             config.tool_tags || [],
             config.execute_as ?? null,
-            resolveCertified(config),
+            certified,
         ]);
         // Replace roles
         await client.query(sql_1.DELETE_CONFIG_ROLES, [config.workflow_type]);
@@ -64,6 +72,9 @@ async function upsertWorkflowConfig(config) {
     finally {
         client.release();
     }
+}
+async function upsertWorkflowConfig(config) {
+    await replaceWorkflowConfig(config, resolveCertified(config));
     return (await (0, read_1.getWorkflowConfig)(config.workflow_type));
 }
 async function deleteWorkflowConfig(workflowType) {
@@ -136,3 +147,39 @@ async function seedWorkflowConfig(config) {
     }
     return inserted;
 }
+/** Order-insensitive comparison for role lists and other unordered arrays. */
+function sortedEqual(a, b) {
+    return (0, node_util_1.isDeepStrictEqual)([...a].sort(), [...b].sort());
+}
+/**
+ * Apply a workflow config at startup (code is source of truth).
+ *
+ * The declared config is diffed against the stored row — jsonb fields as
+ * parsed values, role lists order-insensitively — and written through the
+ * same full-replace transaction the admin surface uses only when something
+ * actually differs. `certified` is explicit-only on this path: an omitted
+ * flag registers the workflow as NOT certified.
+ */
+async function applyWorkflowConfig(config) {
+    const certified = config.certified ?? false;
+    const existing = await (0, read_1.getWorkflowConfig)(config.workflow_type);
+    if (existing) {
+        const unchanged = existing.invocable === config.invocable &&
+            existing.task_queue === config.task_queue &&
+            existing.default_role === config.default_role &&
+            (existing.description ?? null) === (config.description ?? null) &&
+            existing.certified === certified &&
+            (existing.cron_schedule ?? null) === (config.cron_schedule ?? null) &&
+            (existing.execute_as ?? null) === (config.execute_as ?? null) &&
+            sortedEqual(existing.consumes ?? [], config.consumes ?? []) &&
+            sortedEqual(existing.tool_tags ?? [], config.tool_tags ?? []) &&
+            sortedEqual(existing.roles ?? [], config.roles ?? []) &&
+            sortedEqual(existing.invocation_roles ?? [], config.invocation_roles ?? []) &&
+            (0, node_util_1.isDeepStrictEqual)(existing.envelope_schema ?? null, config.envelope_schema ?? null) &&
+            (0, node_util_1.isDeepStrictEqual)(existing.resolver_schema ?? null, config.resolver_schema ?? null);
+        if (unchanged)
+            return 'unchanged';
+    }
+    await replaceWorkflowConfig(config, certified);
+    return 'applied';
+}

package/build/services/domain/seed.d.ts

@@ -1,11 +1,18 @@
 /**
- * Seed the domain dictionary from a host-declared JSON file — the same
- * insert-if-absent + drift-log contract as seedWorkflowConfig/seedMcpServer.
- * The DB row is runtime truth: an existing row is never overwritten; a
- * name/version mismatch against the file logs one drift warning.
+ * Seed the domain dictionary from a host-declared JSON file.
+ *
+ * Default (db-owned): the same insert-if-absent + drift-log contract as
+ * seedWorkflowConfig/seedMcpServer — the DB row is runtime truth, an existing
+ * row is never overwritten, and a name/version mismatch against the file logs
+ * one drift warning.
+ *
+ * With `apply` (code-owned): the file is compared against the stored document
+ * as parsed values; a changed document is written through the same upsert the
+ * PUT path uses, advancing the row's version counter exactly once. An
+ * identical document is a no-op.
  *
  * WARN-ONLY validation: hosts commonly seed roles after long-tail boots, so
  * unknown references log warnings here (the PUT path enforces them hard).
  * Never throws — a missing or malformed file must not brick boot.
  */
-export declare function seedDomainDictionary(dictionaryPath: string): Promise<void>;
+export declare function seedDomainDictionary(dictionaryPath: string, apply?: boolean): Promise<void>;

package/build/services/domain/seed.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.seedDomainDictionary = seedDomainDictionary;
 const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
+const node_util_1 = require("node:util");
 const db_1 = require("../../lib/db");
 const logger_1 = require("../../lib/logger");
 const validate_1 = require("./validate");
@@ -13,16 +14,23 @@ const write_1 = require("./write");
 const read_1 = require("./read");
 const sql_1 = require("./sql");
 /**
- * Seed the domain dictionary from a host-declared JSON file — the same
- * insert-if-absent + drift-log contract as seedWorkflowConfig/seedMcpServer.
- * The DB row is runtime truth: an existing row is never overwritten; a
- * name/version mismatch against the file logs one drift warning.
+ * Seed the domain dictionary from a host-declared JSON file.
+ *
+ * Default (db-owned): the same insert-if-absent + drift-log contract as
+ * seedWorkflowConfig/seedMcpServer — the DB row is runtime truth, an existing
+ * row is never overwritten, and a name/version mismatch against the file logs
+ * one drift warning.
+ *
+ * With `apply` (code-owned): the file is compared against the stored document
+ * as parsed values; a changed document is written through the same upsert the
+ * PUT path uses, advancing the row's version counter exactly once. An
+ * identical document is a no-op.
  *
  * WARN-ONLY validation: hosts commonly seed roles after long-tail boots, so
  * unknown references log warnings here (the PUT path enforces them hard).
  * Never throws — a missing or malformed file must not brick boot.
  */
-async function seedDomainDictionary(dictionaryPath) {
+async function seedDomainDictionary(dictionaryPath, apply = false) {
     const resolved = path_1.default.isAbsolute(dictionaryPath)
         ? dictionaryPath
         : path_1.default.join(process.cwd(), dictionaryPath);
@@ -51,9 +59,20 @@ async function seedDomainDictionary(dictionaryPath) {
                 `(${derived.terms?.length ?? 0} terms, ${derived.runbooks?.length ?? 0} runbooks)`);
             return;
         }
-        // Row already existed — drift check on name/version only (no deep diff).
         const existing = await (0, db_1.getPool)().query(sql_1.GET_DOMAIN);
         const doc = existing.rows[0]?.doc;
+        if (apply) {
+            // Code-owned: compare parsed documents (jsonb loses key order) and
+            // write only on a real change — one version bump per changed file.
+            if (doc && (0, node_util_1.isDeepStrictEqual)(doc, derived))
+                return;
+            await (0, db_1.getPool)().query(sql_1.UPSERT_DOMAIN, [JSON.stringify(derived), null]);
+            read_1.domainCache.invalidate();
+            logger_1.loggerRegistry.info(`[lt-domain] dictionary applied: ${derived.name} v${derived.version} ` +
+                `(${derived.terms?.length ?? 0} terms, ${derived.runbooks?.length ?? 0} runbooks)`);
+            return;
+        }
+        // Row already existed — drift check on name/version only (no deep diff).
         if (doc && (doc.name !== dictionary.name || doc.version !== dictionary.version)) {
             logger_1.loggerRegistry.warn(`[lt-domain] dictionary drift: DB holds "${doc.name}" v${doc.version}, ` +
                 `file declares "${dictionary.name}" v${dictionary.version} — DB is runtime truth`);

package/build/services/mcp/db.d.ts

@@ -38,6 +38,22 @@ export declare function seedMcpServer(input: {
     credentialProviders?: string[];
     toolManifest?: any[];
 }): Promise<boolean>;
+/**
+ * Apply an MCP server declaration at startup (code is source of truth).
+ * Config fields — description, tags, category, compile hints, credential
+ * providers — are written when they differ; runtime state (tool manifest,
+ * connection status) is never touched. Returns 'applied' when the row was
+ * inserted or updated, 'unchanged' when the declaration already matches.
+ */
+export declare function applyMcpServer(input: {
+    name: string;
+    description?: string;
+    tags?: string[];
+    category?: string;
+    compileHints?: string;
+    credentialProviders?: string[];
+    toolManifest?: any[];
+}): Promise<'applied' | 'unchanged'>;
 /**
  * Remove builtin MCP servers that are no longer declared in factory config.
  */