chainlesschain 0.66.0 → 0.81.0

package/src/lib/a2a-protocol.js

@@ -369,3 +369,454 @@ function _notifySubscribers(taskId, status) {
 
 // Export for testing
 export { _subscriptions };
+
+// ─── V2 Canonical Surface (Phase 81) ─────────────────────────────
+
+/**
+ * Frozen task status enum (Phase 81 — adds INPUT_REQUIRED and CANCELED)
+ */
+export const TASK_STATUS_V2 = Object.freeze({
+  SUBMITTED: "submitted",
+  WORKING: "working",
+  INPUT_REQUIRED: "input-required",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELED: "canceled",
+});
+
+/**
+ * Frozen agent card status enum (Phase 81)
+ */
+export const CARD_STATUS_V2 = Object.freeze({
+  ACTIVE: "active",
+  INACTIVE: "inactive",
+  EXPIRED: "expired",
+});
+
+/**
+ * Frozen subscription type enum (Phase 81)
+ */
+export const SUBSCRIPTION_TYPE = Object.freeze({
+  TASK_UPDATE: "task_update",
+  AGENT_STATUS: "agent_status",
+  CAPABILITY_CHANGE: "capability_change",
+});
+
+/**
+ * Frozen capability-negotiation outcome enum (Phase 81)
+ */
+export const NEGOTIATION_RESULT = Object.freeze({
+  COMPATIBLE: "compatible",
+  PARTIAL: "partial",
+  INCOMPATIBLE: "incompatible",
+});
+
+/**
+ * Task state machine — only allow documented transitions.
+ * Terminal: completed, failed, canceled.
+ */
+const _allowedTaskTransitions = Object.freeze({
+  submitted: new Set(["working", "canceled", "failed"]),
+  working: new Set(["input-required", "completed", "failed", "canceled"]),
+  "input-required": new Set(["working", "canceled", "failed"]),
+  completed: new Set(),
+  failed: new Set(),
+  canceled: new Set(),
+});
+
+/**
+ * Agent card status transitions.
+ */
+const _allowedCardTransitions = Object.freeze({
+  active: new Set(["inactive", "expired"]),
+  inactive: new Set(["active", "expired"]),
+  expired: new Set(["active"]),
+});
+
+// In-memory V2 state (parallel to existing DB-backed surface)
+const _v2Tasks = new Map(); // taskId → { agentId, status, input, output, error, history[], deadline, inputPrompt, cancelReason, createdAt, updatedAt }
+const _v2Cards = new Map(); // cardId → { cardId, status, updatedAt }
+const _v2TypedSubs = new Map(); // key `${type}:${resourceId}` → Set<callback>
+
+// ─── Card status & validation ────────────────────────────────────
+
+/**
+ * Validate an A2A agent card against the Phase 81 schema.
+ * Returns { valid, errors[] } — does not throw.
+ */
+export function validateAgentCard(card) {
+  const errors = [];
+  if (!card || typeof card !== "object") {
+    return { valid: false, errors: ["card must be an object"] };
+  }
+  if (!card.name || typeof card.name !== "string") {
+    errors.push("name is required and must be a string");
+  }
+  if (card.capabilities !== undefined && !Array.isArray(card.capabilities)) {
+    errors.push("capabilities must be an array");
+  }
+  if (card.skills !== undefined && !Array.isArray(card.skills)) {
+    errors.push("skills must be an array");
+  }
+  if (card.url !== undefined && typeof card.url !== "string") {
+    errors.push("url must be a string");
+  }
+  if (card.version !== undefined && !/^\d+\.\d+\.\d+$/.test(card.version)) {
+    errors.push("version must follow semver major.minor.patch");
+  }
+  if (
+    card.auth_type !== undefined &&
+    !["none", "bearer", "basic", "oauth2"].includes(card.auth_type)
+  ) {
+    errors.push("auth_type must be one of none|bearer|basic|oauth2");
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Transition an agent card between active/inactive/expired.
+ */
+export function setCardStatus(db, cardId, status) {
+  if (!cardId) throw new Error("Card ID is required");
+  if (!Object.values(CARD_STATUS_V2).includes(status)) {
+    throw new Error(`Invalid card status: ${status}`);
+  }
+  const prev = _v2Cards.get(cardId)?.status || "active";
+  const allowed = _allowedCardTransitions[prev] || new Set();
+  if (prev !== status && !allowed.has(status)) {
+    throw new Error(`Invalid card transition: ${prev} → ${status}`);
+  }
+  const now = nowISO();
+  _v2Cards.set(cardId, { cardId, status, updatedAt: now });
+  if (db) {
+    try {
+      ensureA2ATables(db);
+      db.prepare(
+        `UPDATE a2a_agent_cards SET status = ?, updated_at = ? WHERE id = ?`,
+      ).run(status, now, cardId);
+    } catch (_err) {
+      // DB may not support UPDATE in mock — in-memory state is authoritative
+    }
+  }
+  return { cardId, status, updatedAt: now };
+}
+
+/**
+ * Get a card's V2 status (falls back to 'active' if no V2 entry exists).
+ */
+export function getCardStatusV2(cardId) {
+  return _v2Cards.get(cardId)?.status || "active";
+}
+
+// ─── Task lifecycle V2 ───────────────────────────────────────────
+
+/**
+ * Submit a task with optional timeout tracking.
+ */
+export function sendTaskV2(db, { agentId, input, timeoutMs }) {
+  if (!agentId) throw new Error("Agent ID is required");
+  if (!input) throw new Error("Task input is required");
+  const taskId = generateId("task");
+  const now = nowISO();
+  const deadline =
+    typeof timeoutMs === "number" && timeoutMs > 0
+      ? Date.now() + timeoutMs
+      : null;
+  const task = {
+    taskId,
+    agentId,
+    status: TASK_STATUS_V2.SUBMITTED,
+    input,
+    output: "",
+    error: "",
+    history: [{ status: TASK_STATUS_V2.SUBMITTED, timestamp: now }],
+    deadline,
+    inputPrompt: null,
+    cancelReason: null,
+    createdAt: now,
+    updatedAt: now,
+  };
+  _v2Tasks.set(taskId, task);
+  _notifyTyped(SUBSCRIPTION_TYPE.TASK_UPDATE, taskId, {
+    taskId,
+    status: task.status,
+  });
+  return { taskId, status: task.status, deadline };
+}
+
+function _transitionTask(taskId, nextStatus, patch = {}) {
+  const task = _v2Tasks.get(taskId);
+  if (!task) throw new Error(`Task not found: ${taskId}`);
+  const allowed = _allowedTaskTransitions[task.status] || new Set();
+  if (!allowed.has(nextStatus)) {
+    throw new Error(`Invalid task transition: ${task.status} → ${nextStatus}`);
+  }
+  const now = nowISO();
+  task.status = nextStatus;
+  task.updatedAt = now;
+  task.history.push({
+    status: nextStatus,
+    timestamp: now,
+    ...patch.historyExtra,
+  });
+  if (patch.output !== undefined) task.output = patch.output;
+  if (patch.error !== undefined) task.error = patch.error;
+  if (patch.inputPrompt !== undefined) task.inputPrompt = patch.inputPrompt;
+  if (patch.cancelReason !== undefined) task.cancelReason = patch.cancelReason;
+  _notifyTyped(SUBSCRIPTION_TYPE.TASK_UPDATE, taskId, {
+    taskId,
+    status: nextStatus,
+  });
+  return { taskId, status: nextStatus };
+}
+
+/**
+ * Move a task from submitted → working (or input-required → working).
+ */
+export function startWorking(_db, taskId) {
+  return _transitionTask(taskId, TASK_STATUS_V2.WORKING);
+}
+
+/**
+ * Request user input while working → input-required.
+ */
+export function requestInput(_db, taskId, prompt) {
+  if (!prompt) throw new Error("Prompt is required");
+  return _transitionTask(taskId, TASK_STATUS_V2.INPUT_REQUIRED, {
+    inputPrompt: prompt,
+  });
+}
+
+/**
+ * Provide requested input; input-required → working (clears prompt).
+ */
+export function provideInput(_db, taskId, responseInput) {
+  const task = _v2Tasks.get(taskId);
+  if (!task) throw new Error(`Task not found: ${taskId}`);
+  if (task.status !== TASK_STATUS_V2.INPUT_REQUIRED) {
+    throw new Error(
+      `provideInput requires status input-required, got ${task.status}`,
+    );
+  }
+  const result = _transitionTask(taskId, TASK_STATUS_V2.WORKING, {
+    inputPrompt: null,
+    historyExtra: { response: responseInput },
+  });
+  task.input = `${task.input}\n${responseInput}`;
+  return result;
+}
+
+/**
+ * Mark task complete (from working only).
+ */
+export function completeTaskV2(_db, taskId, output, artifacts = []) {
+  const task = _v2Tasks.get(taskId);
+  if (!task) throw new Error(`Task not found: ${taskId}`);
+  const res = _transitionTask(taskId, TASK_STATUS_V2.COMPLETED, {
+    output: output || "",
+  });
+  task.artifacts = artifacts;
+  return res;
+}
+
+/**
+ * Mark task failed.
+ */
+export function failTaskV2(_db, taskId, error) {
+  return _transitionTask(taskId, TASK_STATUS_V2.FAILED, {
+    error: error || "Unknown error",
+  });
+}
+
+/**
+ * Cancel a non-terminal task.
+ */
+export function cancelTask(_db, taskId, reason) {
+  return _transitionTask(taskId, TASK_STATUS_V2.CANCELED, {
+    cancelReason: reason || "user_requested",
+  });
+}
+
+/**
+ * Check task timeout — if past deadline and not terminal, auto-fails.
+ * Returns { timedOut: boolean, status }.
+ */
+export function checkTaskTimeout(_db, taskId, now = Date.now()) {
+  const task = _v2Tasks.get(taskId);
+  if (!task) throw new Error(`Task not found: ${taskId}`);
+  const terminal = [
+    TASK_STATUS_V2.COMPLETED,
+    TASK_STATUS_V2.FAILED,
+    TASK_STATUS_V2.CANCELED,
+  ];
+  if (terminal.includes(task.status)) {
+    return { timedOut: false, status: task.status };
+  }
+  if (task.deadline && now >= task.deadline) {
+    _transitionTask(taskId, TASK_STATUS_V2.FAILED, { error: "timeout" });
+    return { timedOut: true, status: TASK_STATUS_V2.FAILED };
+  }
+  return { timedOut: false, status: task.status };
+}
+
+/**
+ * Get V2 task snapshot.
+ */
+export function getTaskV2(taskId) {
+  const task = _v2Tasks.get(taskId);
+  if (!task) throw new Error(`Task not found: ${taskId}`);
+  return { ...task, history: [...task.history] };
+}
+
+/**
+ * List V2 tasks (optional filter by agentId / status).
+ */
+export function listTasksV2({ agentId, status } = {}) {
+  const out = [];
+  for (const task of _v2Tasks.values()) {
+    if (agentId && task.agentId !== agentId) continue;
+    if (status && task.status !== status) continue;
+    out.push({ ...task, history: [...task.history] });
+  }
+  return out;
+}
+
+// ─── Typed subscriptions ─────────────────────────────────────────
+
+function _notifyTyped(type, resourceId, payload) {
+  const key = `${type}:${resourceId}`;
+  const subs = _v2TypedSubs.get(key);
+  if (subs) {
+    for (const cb of subs) {
+      try {
+        cb(payload);
+      } catch (_err) {
+        // Subscriber error should not break lifecycle
+      }
+    }
+  }
+}
+
+/**
+ * Subscribe with typed filter.
+ */
+export function subscribeTyped(type, resourceId, callback) {
+  if (!Object.values(SUBSCRIPTION_TYPE).includes(type)) {
+    throw new Error(`Invalid subscription type: ${type}`);
+  }
+  if (!resourceId) throw new Error("resourceId is required");
+  const key = `${type}:${resourceId}`;
+  if (!_v2TypedSubs.has(key)) _v2TypedSubs.set(key, new Set());
+  _v2TypedSubs.get(key).add(callback);
+  return () => {
+    const subs = _v2TypedSubs.get(key);
+    if (subs) {
+      subs.delete(callback);
+      if (subs.size === 0) _v2TypedSubs.delete(key);
+    }
+  };
+}
+
+// ─── Capability negotiation V2 ───────────────────────────────────
+
+function _parseVersion(v) {
+  if (typeof v !== "string") return null;
+  const m = v.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!m) return null;
+  return { major: +m[1], minor: +m[2], patch: +m[3] };
+}
+
+function _semverCompatible(clientVer, serverVer) {
+  const c = _parseVersion(clientVer);
+  const s = _parseVersion(serverVer);
+  if (!c || !s) return true; // Unknown versions → assume compatible
+  if (c.major !== s.major) return false;
+  // Minor: client can be ≤ server minor
+  if (c.minor > s.minor) return false;
+  return true;
+}
+
+/**
+ * Negotiate capabilities against an agent's declared skills.
+ * @param {object} opts — { required: string[], preferred?: string[], version?: string }
+ * @param {object} agentCard — { capabilities: string[], version?: string }
+ */
+export function negotiateCapabilityV2(
+  agentCard,
+  { required = [], preferred = [], version },
+) {
+  if (!agentCard || typeof agentCard !== "object") {
+    throw new Error("agentCard is required");
+  }
+  const caps = Array.isArray(agentCard.capabilities)
+    ? agentCard.capabilities
+    : [];
+  const missingRequired = required.filter((c) => !caps.includes(c));
+  const supportedPreferred = preferred.filter((c) => caps.includes(c));
+  const missingPreferred = preferred.filter((c) => !caps.includes(c));
+  const versionOk = version
+    ? _semverCompatible(version, agentCard.version)
+    : true;
+
+  let result;
+  if (!versionOk || missingRequired.length > 0) {
+    result = NEGOTIATION_RESULT.INCOMPATIBLE;
+  } else if (missingPreferred.length > 0) {
+    result = NEGOTIATION_RESULT.PARTIAL;
+  } else {
+    result = NEGOTIATION_RESULT.COMPATIBLE;
+  }
+  return {
+    result,
+    missingRequired,
+    supportedPreferred,
+    missingPreferred,
+    versionOk,
+  };
+}
+
+// ─── Stats V2 ────────────────────────────────────────────────────
+
+export function getA2AStatsV2() {
+  const byStatus = {};
+  for (const v of Object.values(TASK_STATUS_V2)) byStatus[v] = 0;
+  let withDeadline = 0;
+  let canceled = 0;
+  for (const task of _v2Tasks.values()) {
+    byStatus[task.status] = (byStatus[task.status] || 0) + 1;
+    if (task.deadline) withDeadline += 1;
+    if (task.cancelReason) canceled += 1;
+  }
+  const cardsByStatus = {};
+  for (const v of Object.values(CARD_STATUS_V2)) cardsByStatus[v] = 0;
+  for (const c of _v2Cards.values()) {
+    cardsByStatus[c.status] = (cardsByStatus[c.status] || 0) + 1;
+  }
+  return {
+    tasks: {
+      total: _v2Tasks.size,
+      byStatus,
+      withDeadline,
+      canceledWithReason: canceled,
+    },
+    cards: {
+      tracked: _v2Cards.size,
+      byStatus: cardsByStatus,
+    },
+    subscriptions: {
+      legacy: _subscriptions.size,
+      typed: _v2TypedSubs.size,
+    },
+  };
+}
+
+/**
+ * Reset V2-only in-memory state (for tests).
+ */
+export function _resetV2State() {
+  _v2Tasks.clear();
+  _v2Cards.clear();
+  _v2TypedSubs.clear();
+}
+
+export { _v2Tasks, _v2Cards, _v2TypedSubs };

package/src/lib/app-builder.js

@@ -503,3 +503,242 @@ export function deployApp(db, appId, options = {}) {
   const deployedAt = new Date().toISOString();
   return { appId, outputDir, files: fileNames, deployedAt };
 }
+
+// ─── Phase 93 V2 surface (strictly additive) ───────────────────────────
+
+export const COMPONENT_CATEGORY = Object.freeze({
+  INPUT: "input",
+  DISPLAY: "display",
+  CHART: "chart",
+  LAYOUT: "layout",
+  OVERLAY: "overlay",
+});
+
+export const DATASOURCE_TYPE = Object.freeze({
+  REST: "rest",
+  GRAPHQL: "graphql",
+  DATABASE: "database",
+  CSV: "csv",
+});
+
+export const APP_STATUS = Object.freeze({
+  DRAFT: "draft",
+  PUBLISHED: "published",
+  ARCHIVED: "archived",
+});
+
+const _allowedStatusTransitions = Object.freeze({
+  draft: new Set(["published", "archived"]),
+  published: new Set(["draft", "archived"]),
+  archived: new Set(["draft"]),
+});
+
+const _v2DataSources = new Map();
+const _v2StatusHistory = new Map();
+
+function _isValidStatusTransition(from, to) {
+  if (from === to) return true;
+  const allowed = _allowedStatusTransitions[from];
+  return !!(allowed && allowed.has(to));
+}
+
+export function listComponentsV2({ category } = {}) {
+  const all = listComponents();
+  if (!category) return all.map((c) => ({ ...c }));
+  const valid = Object.values(COMPONENT_CATEGORY);
+  if (!valid.includes(category)) {
+    throw new Error(
+      `Invalid category '${category}'. Expected one of ${valid.join(", ")}`,
+    );
+  }
+  return all.filter((c) => c.category === category).map((c) => ({ ...c }));
+}
+
+export function registerDataSourceV2(db, { appId, name, type, config = {} }) {
+  const valid = Object.values(DATASOURCE_TYPE);
+  if (!valid.includes(type)) {
+    throw new Error(
+      `Invalid datasource type '${type}'. Expected one of ${valid.join(", ")}`,
+    );
+  }
+  if (!appId) throw new Error("appId is required");
+  if (!name) throw new Error("name is required");
+
+  const result = addDataSource(db, appId, name, type, config);
+  _v2DataSources.set(result.id, { ...result, config, validated: false });
+  return result;
+}
+
+export function testDataSourceConnection(dataSourceId) {
+  const ds = _v2DataSources.get(dataSourceId);
+  if (!ds) {
+    return { dataSourceId, ok: false, reason: "datasource not found" };
+  }
+  const config = ds.config || {};
+  let ok = false;
+  let reason = "";
+  switch (ds.type) {
+    case DATASOURCE_TYPE.REST:
+      ok = typeof config.url === "string" && config.url.length > 0;
+      reason = ok ? "ok" : "missing url";
+      break;
+    case DATASOURCE_TYPE.GRAPHQL:
+      ok = typeof config.endpoint === "string" && config.endpoint.length > 0;
+      reason = ok ? "ok" : "missing endpoint";
+      break;
+    case DATASOURCE_TYPE.DATABASE:
+      ok = typeof config.host === "string" && config.host.length > 0;
+      reason = ok ? "ok" : "missing host";
+      break;
+    case DATASOURCE_TYPE.CSV:
+      ok = typeof config.path === "string" && config.path.length > 0;
+      reason = ok ? "ok" : "missing path";
+      break;
+    default:
+      reason = "unknown type";
+  }
+  if (ok) {
+    ds.validated = true;
+    _v2DataSources.set(dataSourceId, ds);
+  }
+  return { dataSourceId, type: ds.type, ok, reason };
+}
+
+export function updateAppStatus(db, { appId, status }) {
+  const valid = Object.values(APP_STATUS);
+  if (!valid.includes(status)) {
+    throw new Error(
+      `Invalid status '${status}'. Expected one of ${valid.join(", ")}`,
+    );
+  }
+  const app = getApp(db, appId);
+  if (!app) throw new Error(`App '${appId}' not found`);
+
+  const currentStatus =
+    app.status === "deployed" ? APP_STATUS.PUBLISHED : app.status;
+  if (!_isValidStatusTransition(currentStatus, status)) {
+    throw new Error(`Invalid status transition: ${currentStatus} → ${status}`);
+  }
+
+  db.prepare(
+    `UPDATE lowcode_apps SET status = ?, updated_at = datetime('now') WHERE id = ?`,
+  ).run(status, appId);
+  if (_apps.has(appId)) _apps.get(appId).status = status;
+
+  const hist = _v2StatusHistory.get(appId) || [];
+  hist.push({
+    from: currentStatus,
+    to: status,
+    at: new Date().toISOString(),
+  });
+  _v2StatusHistory.set(appId, hist);
+  return { appId, status, previous: currentStatus };
+}
+
+export function archiveApp(db, appId) {
+  return updateAppStatus(db, { appId, status: APP_STATUS.ARCHIVED });
+}
+
+export function getStatusHistory(appId) {
+  return (_v2StatusHistory.get(appId) || []).slice();
+}
+
+export function cloneApp(db, { sourceId, newName }) {
+  const source = getApp(db, sourceId);
+  if (!source) throw new Error(`App '${sourceId}' not found`);
+  const cloned = createApp(db, {
+    name: newName || `${source.name} (Copy)`,
+    description: source.description,
+    platform: source.platform,
+    design: source.design,
+  });
+  // Persist the copied design so version snapshot matches source
+  if (
+    source.design &&
+    source.design.components &&
+    source.design.components.length > 0
+  ) {
+    saveDesign(db, cloned.id, source.design);
+  }
+  return { sourceId, clonedId: cloned.id, name: cloned.name };
+}
+
+export function exportAppJSON(db, appId) {
+  const app = getApp(db, appId);
+  if (!app) throw new Error(`App '${appId}' not found`);
+  const legacy = exportApp(appId);
+  return {
+    schema: "chainlesschain.lowcode.v2",
+    exportedAt: new Date().toISOString(),
+    app,
+    dataSources: legacy.dataSources,
+    versions: legacy.versions,
+  };
+}
+
+export function importAppJSON(db, json) {
+  if (!json || typeof json !== "object") {
+    throw new Error("import payload must be a JSON object");
+  }
+  if (json.schema !== "chainlesschain.lowcode.v2") {
+    throw new Error(
+      `unsupported schema '${json.schema}'. Expected 'chainlesschain.lowcode.v2'`,
+    );
+  }
+  if (!json.app || !json.app.name) {
+    throw new Error("import payload missing app.name");
+  }
+  const imported = createApp(db, {
+    name: json.app.name,
+    description: json.app.description || "",
+    platform: json.app.platform || "web",
+    design: json.app.design || { components: [], layout: {} },
+  });
+  let dsCount = 0;
+  for (const ds of json.dataSources || []) {
+    if (!ds.type || !ds.name) continue;
+    if (!Object.values(DATASOURCE_TYPE).includes(ds.type)) continue;
+    registerDataSourceV2(db, {
+      appId: imported.id,
+      name: ds.name,
+      type: ds.type,
+      config: ds.config || {},
+    });
+    dsCount++;
+  }
+  return { importedId: imported.id, name: imported.name, dataSources: dsCount };
+}
+
+export function getLowcodeStatsV2(db) {
+  const rows = db.prepare(`SELECT status, platform FROM lowcode_apps`).all();
+  const byStatus = { draft: 0, published: 0, archived: 0, deployed: 0 };
+  const byPlatform = {};
+  for (const r of rows) {
+    const s = r.status || "draft";
+    byStatus[s] = (byStatus[s] || 0) + 1;
+    const p = r.platform || "web";
+    byPlatform[p] = (byPlatform[p] || 0) + 1;
+  }
+
+  const dsRows = db.prepare(`SELECT type FROM lowcode_datasources`).all();
+  const byDataSourceType = {};
+  for (const r of dsRows) {
+    byDataSourceType[r.type] = (byDataSourceType[r.type] || 0) + 1;
+  }
+
+  return {
+    totalApps: rows.length,
+    byStatus,
+    byPlatform,
+    dataSources: {
+      total: dsRows.length,
+      byType: byDataSourceType,
+    },
+    componentsAvailable: listComponents().length,
+  };
+}
+
+export function _resetV2State() {
+  _v2DataSources.clear();
+  _v2StatusHistory.clear();
+}