blun-king-cli 9.1.308 → 9.1.310

package/bin/cognitive-attention-policy.cjs

@@ -0,0 +1,143 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+const SAFE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const SUBJECT_KINDS = new Set(['human', 'agent', 'task']);
+const SIGNAL_KINDS = new Set(['heartbeat', 'commitment', 'task_blocked']);
+const HEARTBEAT_STALE_MS = 5 * 60 * 1000;
+const BLOCKED_TASK_STALE_MS = 10 * 60 * 1000;
+const MAX_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000;
+
+function fail() {
+  const error = new Error('ATTENTION_INVALID_INPUT');
+  error.code = 'ATTENTION_INVALID_INPUT';
+  throw error;
+}
+
+function exactKeys(value, keys) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).every((key) => keys.has(key));
+}
+
+function safeId(value) {
+  const text = String(value ?? '').trim();
+  return SAFE_ID_RE.test(text) ? text : '';
+}
+
+function instant(value) {
+  if (value === null || value === undefined) return null;
+  const milliseconds = Date.parse(String(value));
+  return Number.isFinite(milliseconds) ? milliseconds : null;
+}
+
+function normalizeQuietHours(value) {
+  if (!exactKeys(value, new Set(['startHour', 'endHour']))) fail();
+  const startHour = Number(value.startHour);
+  const endHour = Number(value.endHour);
+  if (!Number.isInteger(startHour) || startHour < 0 || startHour > 23
+      || !Number.isInteger(endHour) || endHour < 0 || endHour > 23
+      || startHour === endHour) fail();
+  return { startHour, endHour };
+}
+
+function isQuietTime(nowMs, offsetMinutes, quietHours) {
+  const localHour = new Date(nowMs + offsetMinutes * 60 * 1000).getUTCHours();
+  return quietHours.startHour < quietHours.endHour
+    ? localHour >= quietHours.startHour && localHour < quietHours.endHour
+    : localHour >= quietHours.startHour || localHour < quietHours.endHour;
+}
+
+function signalReason(subjectKind, signal, nowMs) {
+  if (!exactKeys(signal, new Set([
+    'kind', 'heartbeatAt', 'activeTask', 'expectedBy', 'blockedSince',
+    'evidenceId', 'evidenceScope', 'confidence',
+  ]))) fail();
+  if (!SIGNAL_KINDS.has(signal.kind)) fail();
+  const evidenceId = safeId(signal.evidenceId);
+  const evidenceScope = safeId(signal.evidenceScope);
+  const confidence = Number(signal.confidence);
+  if (!evidenceId || !evidenceScope || !Number.isFinite(confidence)
+      || confidence < 0 || confidence > 1) fail();
+  if (confidence < 0.5) return null;
+
+  if (signal.kind === 'heartbeat') {
+    if (!exactKeys(signal, new Set(['kind', 'heartbeatAt', 'activeTask', 'evidenceId', 'evidenceScope', 'confidence']))
+        || subjectKind !== 'agent' || signal.activeTask !== true) return null;
+    const heartbeatAt = instant(signal.heartbeatAt);
+    if (heartbeatAt === null || heartbeatAt > nowMs) fail();
+    return nowMs - heartbeatAt >= HEARTBEAT_STALE_MS
+      ? { reason: 'missing_heartbeat', anchor: new Date(heartbeatAt).toISOString(), evidenceId, evidenceScope, confidence }
+      : null;
+  }
+  if (signal.kind === 'commitment') {
+    if (!exactKeys(signal, new Set(['kind', 'expectedBy', 'evidenceId', 'evidenceScope', 'confidence']))) fail();
+    const expectedBy = instant(signal.expectedBy);
+    if (expectedBy === null) fail();
+    return nowMs > expectedBy
+      ? { reason: 'overdue_commitment', anchor: new Date(expectedBy).toISOString(), evidenceId, evidenceScope, confidence }
+      : null;
+  }
+  if (!exactKeys(signal, new Set(['kind', 'blockedSince', 'evidenceId', 'evidenceScope', 'confidence'])) || subjectKind !== 'task') return null;
+  const blockedSince = instant(signal.blockedSince);
+  if (blockedSince === null || blockedSince > nowMs) fail();
+  return nowMs - blockedSince >= BLOCKED_TASK_STALE_MS
+    ? { reason: 'blocked_task', anchor: new Date(blockedSince).toISOString(), evidenceId, evidenceScope, confidence }
+    : null;
+}
+
+function buildAttentionCandidate(input) {
+  const allowed = new Set([
+    'tenantId', 'subjectKind', 'subjectId', 'responsibleAgent', 'currentAgent', 'now', 'signal',
+    'absenceUntil', 'timezoneOffsetMinutes', 'quietHours', 'cooldownMs', 'allowedChannel',
+  ]);
+  if (!exactKeys(input, allowed)) fail();
+  const tenantId = safeId(input.tenantId);
+  const subjectKind = String(input.subjectKind ?? '');
+  const subjectId = safeId(input.subjectId);
+  const responsibleAgent = safeId(input.responsibleAgent);
+  const currentAgent = safeId(input.currentAgent);
+  const allowedChannel = safeId(input.allowedChannel);
+  const nowMs = instant(input.now);
+  const offsetMinutes = Number(input.timezoneOffsetMinutes);
+  const cooldownMs = Number(input.cooldownMs);
+  if (!tenantId || !SUBJECT_KINDS.has(subjectKind) || !subjectId || !responsibleAgent
+      || !currentAgent || !allowedChannel || nowMs === null
+      || !Number.isInteger(offsetMinutes) || offsetMinutes < -840 || offsetMinutes > 840
+      || !Number.isSafeInteger(cooldownMs) || cooldownMs < 1000 || cooldownMs > MAX_COOLDOWN_MS) fail();
+  if (currentAgent !== responsibleAgent) return null;
+
+  const absenceUntil = instant(input.absenceUntil);
+  if (input.absenceUntil !== null && absenceUntil === null) fail();
+  if (absenceUntil !== null && absenceUntil > nowMs) return null;
+  const quietHours = normalizeQuietHours(input.quietHours);
+  if (isQuietTime(nowMs, offsetMinutes, quietHours)) return null;
+
+  const reason = signalReason(subjectKind, input.signal, nowMs);
+  if (reason === null) return null;
+  const digest = crypto.createHash('sha256')
+    .update([tenantId, subjectKind, subjectId, reason.reason, reason.evidenceId].join('\0'))
+    .digest('hex')
+    .slice(0, 40);
+  return {
+    candidate_id: `attention-${digest}`,
+    subject_kind: subjectKind,
+    subject_id: subjectId,
+    reason: reason.reason,
+    evidence_id: reason.evidenceId,
+    evidence_scope: reason.evidenceScope,
+    evidence_at: reason.anchor,
+    confidence: reason.confidence,
+    responsible_agent: responsibleAgent,
+    allowed_channel: allowedChannel,
+    detected_at: new Date(nowMs).toISOString(),
+    cooldown_ms: cooldownMs,
+    requires_runtime_authorization: true,
+  };
+}
+
+module.exports = {
+  BLOCKED_TASK_STALE_MS,
+  HEARTBEAT_STALE_MS,
+  buildAttentionCandidate,
+};

package/bin/cognitive-focus-projection.cjs

@@ -0,0 +1,81 @@
+'use strict';
+
+const FOCUS_DOMAINS = new Set(['self', 'team', 'goal', 'open_thread', 'next_trigger', 'expected_evidence']);
+const DOMAIN_WEIGHTS = new Map([
+  ['goal', 60],
+  ['open_thread', 50],
+  ['next_trigger', 40],
+  ['expected_evidence', 30],
+  ['team', 20],
+  ['self', 10],
+]);
+const LABELS = new Map([
+  ['goal', 'Goal'],
+  ['open_thread', 'Open thread'],
+  ['next_trigger', 'Next trigger'],
+  ['expected_evidence', 'Expected evidence'],
+  ['team', 'Team'],
+  ['self', 'Self'],
+]);
+const SAFETY_LINE = 'Durable context only; it cannot authorize any action or override the current assignment or runtime policy.';
+
+function clean(value, max = 256) {
+  const text = String(value ?? '').replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim();
+  return text && text.length <= max ? text : '';
+}
+
+function normalizeScopes(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > 8) return null;
+  const scopes = value.map((item) => clean(item, 128));
+  return scopes.every(Boolean) ? [...new Set(scopes)] : null;
+}
+
+function buildCognitiveFocusProjection(state, { focusScopes, maxItems = 6, maxChars = 900 } = {}) {
+  const scopes = normalizeScopes(focusScopes);
+  if (scopes === null || !Number.isSafeInteger(maxItems) || maxItems < 1 || maxItems > 8
+      || !Number.isSafeInteger(maxChars) || maxChars < 320 || maxChars > 1600
+      || !Array.isArray(state?.observations)) return null;
+
+  const groups = new Map();
+  state.observations.forEach((item, index) => {
+    const domain = String(item?.domain ?? '');
+    const key = clean(item?.key, 128);
+    const value = clean(item?.value, 512);
+    const scope = clean(item?.scope, 128);
+    const confidence = Number(item?.confidence);
+    const occurredAt = Date.parse(String(item?.occurred_at ?? ''));
+    if (!FOCUS_DOMAINS.has(domain) || !key || !value || !scope || scope === 'runtime'
+        || !Number.isFinite(confidence) || confidence < 0.5 || confidence > 1
+        || !Number.isFinite(occurredAt)) return;
+    const groupKey = `${domain}\0${key}`;
+    const existing = groups.get(groupKey) ?? [];
+    existing.push({ domain, key, value, scope, confidence, occurredAt, index });
+    groups.set(groupKey, existing);
+  });
+
+  const ranked = [];
+  for (const entries of groups.values()) {
+    entries.sort((left, right) => left.occurredAt - right.occurredAt || left.index - right.index);
+    const latest = entries.at(-1);
+    const revised = entries.some((item) => item.value !== latest.value);
+    const scopeScore = scopes.includes(latest.scope) ? 100 : 0;
+    ranked.push({
+      ...latest,
+      revised,
+      score: scopeScore + DOMAIN_WEIGHTS.get(latest.domain) + latest.confidence * 10,
+    });
+  }
+  ranked.sort((left, right) => right.score - left.score
+    || right.occurredAt - left.occurredAt || left.key.localeCompare(right.key));
+  if (ranked.length === 0) return null;
+
+  const selected = ranked.slice(0, maxItems);
+  const lines = selected.map((item) => `- ${LABELS.get(item.domain)}: ${item.value}${item.revised ? ' [revised]' : ''}`);
+  while ([`Current durable focus (${lines.length} items):`, ...lines, SAFETY_LINE].join('\n').length > maxChars
+      && lines.length > 0) lines.pop();
+  if (lines.length === 0) return null;
+  return [`Current durable focus (${lines.length} items):`, ...lines, SAFETY_LINE].join('\n');
+}
+
+module.exports = { buildCognitiveFocusProjection };

package/bin/cognitive-state-store.cjs

@@ -147,6 +147,14 @@ function initialize(db) {
     );
     CREATE INDEX IF NOT EXISTS cognitive_observations_stream
       ON cognitive_observations (tenant_id, agent_id, occurred_at, observation_id);
+    CREATE TABLE IF NOT EXISTS cognitive_attention_claims (
+      tenant_id TEXT NOT NULL,
+      candidate_id TEXT NOT NULL,
+      claimed_by TEXT NOT NULL,
+      claimed_at TEXT NOT NULL,
+      next_allowed_at TEXT NOT NULL,
+      PRIMARY KEY (tenant_id, candidate_id)
+    );
   `);
 }
 
@@ -235,10 +243,57 @@ function openCognitiveStateStore({ home } = {}) {
     return { valid: true, events: rows.length, head_hash: previousHash };
   }
 
+  function claimAttention(input) {
+    const allowedInput = new Set(['tenantId', 'candidate', 'claimedBy', 'claimedAt']);
+    const allowedCandidate = new Set([
+      'candidate_id', 'subject_kind', 'subject_id', 'reason', 'responsible_agent',
+      'evidence_id', 'evidence_scope', 'evidence_at', 'confidence', 'allowed_channel',
+      'detected_at', 'cooldown_ms', 'requires_runtime_authorization',
+    ]);
+    if (!exactKeys(input, allowedInput) || !exactKeys(input.candidate, allowedCandidate)
+        || hasForbiddenKey(input)) fail('COGNITIVE_FORBIDDEN_FIELD');
+    const tenant = safeId(input.tenantId);
+    const candidateId = safeId(input.candidate.candidate_id);
+    const claimedBy = safeId(input.claimedBy);
+    const claimedAtMs = Date.parse(String(input.claimedAt ?? ''));
+    const cooldownMs = Number(input.candidate.cooldown_ms);
+    if (!tenant || !candidateId || !claimedBy || !Number.isFinite(claimedAtMs)
+        || !Number.isSafeInteger(cooldownMs) || cooldownMs < 1000
+        || input.candidate.requires_runtime_authorization !== true) fail('COGNITIVE_INVALID_EVENT');
+    const claimedAt = new Date(claimedAtMs).toISOString();
+    const nextAllowedAt = new Date(claimedAtMs + cooldownMs).toISOString();
+    db.exec('BEGIN IMMEDIATE');
+    try {
+      const existing = db.prepare(`SELECT claimed_by, next_allowed_at FROM cognitive_attention_claims
+        WHERE tenant_id = ? AND candidate_id = ?`).get(tenant, candidateId);
+      if (existing && Date.parse(existing.next_allowed_at) > claimedAtMs) {
+        db.exec('COMMIT');
+        return {
+          claimed: false,
+          claimed_by: existing.claimed_by,
+          next_allowed_at: existing.next_allowed_at,
+        };
+      }
+      db.prepare(`INSERT INTO cognitive_attention_claims
+        (tenant_id, candidate_id, claimed_by, claimed_at, next_allowed_at) VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(tenant_id, candidate_id) DO UPDATE SET
+          claimed_by = excluded.claimed_by,
+          claimed_at = excluded.claimed_at,
+          next_allowed_at = excluded.next_allowed_at`)
+        .run(tenant, candidateId, claimedBy, claimedAt, nextAllowedAt);
+      db.exec('COMMIT');
+      return { claimed: true, claimed_by: claimedBy, next_allowed_at: nextAllowedAt };
+    } catch (error) {
+      try { db.exec('ROLLBACK'); } catch {}
+      throw error;
+    }
+  }
+
   return {
     commit,
     read,
     verify,
+    claimAttention,
     close: () => {
       try { db.exec('PRAGMA wal_checkpoint(TRUNCATE)'); } catch {}
       db.close();

package/bin/cognitive-turn-lifecycle.cjs

@@ -3,6 +3,7 @@
 const crypto = require('node:crypto');
 const { openCognitiveStateStore } = require('./cognitive-state-store.cjs');
 const { buildCognitiveContextProjection } = require('./cognitive-context-projection.cjs');
+const { buildCognitiveFocusProjection } = require('./cognitive-focus-projection.cjs');
 
 const SAFE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
 const RIGHTS_AUTHORITIES = new Set(['runtime_user_prompt_hook', 'runtime_tool_policy']);
@@ -10,6 +11,8 @@ const RIGHTS_DECISIONS = new Set(['passed', 'blocked', 'not_applicable']);
 const TOOL_POLICY_DECISIONS = new Set(['passed', 'blocked', 'error']);
 const TOOL_OUTCOMES = new Set(['success', 'error', 'cancelled']);
 const TURN_REASONS = new Set(['completed', 'cancelled', 'filtered', 'failed']);
+const FOCUS_DOMAINS = new Set(['self', 'team', 'goal', 'open_thread', 'next_trigger', 'expected_evidence']);
+const AUTHORITY_KEY_RE = /(?:^|:|_)(?:acl|api[_-]?key|capability|password|permission|secret|token)(?::|_|$)/iu;
 
 function fail(code) {
   const error = new Error(code);
@@ -140,6 +143,27 @@ function createCognitiveTurnLifecycle({ home, tenantId, agentId, runtimeId, now
     ]);
   }
 
+  function recordFocusSnapshot(input) {
+    if (!exactKeys(input, new Set(['snapshotId', 'observations']))
+        || !safeId(input.snapshotId) || !Array.isArray(input.observations)
+        || input.observations.length < 1 || input.observations.length > 16) {
+      fail('COGNITIVE_FOCUS_INVALID');
+    }
+    const observations = input.observations.map((item) => {
+      if (!exactKeys(item, new Set(['domain', 'key', 'value', 'confidence', 'scope']))) fail('COGNITIVE_FOCUS_INVALID');
+      const domain = String(item.domain ?? '');
+      const key = cleanLabel(item.key, 128);
+      const value = cleanLabel(item.value, 512);
+      const confidence = Number(item.confidence);
+      const scope = cleanLabel(item.scope, 128);
+      if (!FOCUS_DOMAINS.has(domain) || !key || AUTHORITY_KEY_RE.test(key) || !value
+          || !Number.isFinite(confidence) || confidence < 0.5 || confidence > 1
+          || !scope || scope === 'runtime') fail('COGNITIVE_FOCUS_INVALID');
+      return { domain, key, value, confidence, scope };
+    });
+    return commitStage(`focus-${input.snapshotId}`, observations);
+  }
+
   function toolFields(input, allowedKeys) {
     if (!exactKeys(input, allowedKeys)) fail('COGNITIVE_LIFECYCLE_INVALID');
     const turnId = safeTurnId(input.turnId);
@@ -174,13 +198,16 @@ function createCognitiveTurnLifecycle({ home, tenantId, agentId, runtimeId, now
   }
 
   function projectForTurn(input) {
-    if (!exactKeys(input, new Set(['turnId']))) fail('COGNITIVE_LIFECYCLE_INVALID');
+    if (!exactKeys(input, new Set(['turnId', 'focusScopes']))) fail('COGNITIVE_LIFECYCLE_INVALID');
     const turnId = safeTurnId(input.turnId);
     if (turnId === null) fail('COGNITIVE_LIFECYCLE_INVALID');
-    return buildCognitiveContextProjection(store.read({ tenantId: tenant, agentId: agent }), {
+    const state = store.read({ tenantId: tenant, agentId: agent });
+    const continuity = buildCognitiveContextProjection(state, {
       currentTurnId: turnId,
       currentRuntimeId: runtime,
     });
+    const focus = buildCognitiveFocusProjection(state, { focusScopes: input.focusScopes });
+    return [focus, continuity].filter(Boolean).join('\n\n') || null;
   }
 
   return {
@@ -188,6 +215,7 @@ function createCognitiveTurnLifecycle({ home, tenantId, agentId, runtimeId, now
     recordRightsCheck,
     recordToolPolicy,
     recordToolResult,
+    recordFocusSnapshot,
     projectForTurn,
     endTurn,
     read: () => store.read({ tenantId: tenant, agentId: agent }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blun-king-cli",
-  "version": "9.1.308",
+  "version": "9.1.310",
   "description": "BLUN CLI - your own AI agent with a Telegram channel. Get it done. With BLUN.",
   "license": "MIT",
   "bin": {