Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Pure state helpers for the Persistent Mind's progressive tool exposure
* (issue #7624): a small always-on core plus family-scoped explicit
* activation with a short, turn-scoped retention lease.
*
* Retention here is a SELECTION HINT, never an authority grant. Every helper
* in this module only decides what tool schemas are SHOWN to the mind on its
* next prompt. The capability/`granted` gate in cosToolRegistry.js runs
* independently at both selection and execution time, so a lease can never
* widen what the mind is allowed to do — a revoked capability drops a leased
* tool immediately regardless of anything recorded here.
*/
import { z } from 'zod';
// Families mirror the existing capability/scope groupings already declared
// per tool in cosToolRegistry.js (the precedent is TOOL_GROUPS/GROUP_INTENT
// in server/services/voice/tools.js) — no new vocabulary.
export const TOOL_ACTIVATION_FAMILIES = Object.freeze(['tasks', 'issues', 'reports', 'mind', 'eidoverse', 'recipes', 'voice']);
export const TOOL_ACTIVATION_LIMITS = Object.freeze({
MIN_RETENTION_TURNS: 0,
MAX_RETENTION_TURNS: 20,
MAX_TARGET_TOOLS: 5,
});
// 0 is deliberately "one-turn behaviour": activating a family only expands it
// for the turn that activated it, with nothing persisted for the next one.
export const DEFAULT_TOOL_ACTIVATION_RETENTION_TURNS = 3;
export const toolActivationFamilySchema = z.enum(TOOL_ACTIVATION_FAMILIES);
export const toolsActivateInputSchema = z.object({
families: z.array(toolActivationFamilySchema).min(1).max(TOOL_ACTIVATION_FAMILIES.length),
toolNames: z.array(z.string().trim().min(1).max(200)).min(1).max(TOOL_ACTIVATION_LIMITS.MAX_TARGET_TOOLS).optional(),
}).strict();
export const toolsDeactivateInputSchema = z.object({
// Omitted clears every currently-selected/leased family.
families: z.array(toolActivationFamilySchema).min(1).max(TOOL_ACTIVATION_FAMILIES.length).optional(),
}).strict();
const isValidFamily = (value) => TOOL_ACTIVATION_FAMILIES.includes(value);
// A lease VALUE of 0 is meaningful — it means "this is the family's last
// turn, still fully exposed" (see agePersistentMindToolActivation) — so
// stored leases accept zero. Only a fresh ACTIVATION (below) requires a
// strictly positive retention count; activating with 0 persists nothing.
const isNonNegativeInt = (value) => Number.isSafeInteger(value) && value >= 0;
const isPositiveInt = (value) => Number.isSafeInteger(value) && value > 0;
export function createDefaultPersistentMindToolActivation() {
return { leases: {}, lastAgedTurnId: null };
}
/** Normalize hand-edited or legacy state: unknown families and negative/non-integer counts are dropped. */
export function normalizePersistentMindToolActivation(raw) {
const leases = {};
const source = raw?.leases;
if (source && typeof source === 'object' && !Array.isArray(source)) {
for (const family of TOOL_ACTIVATION_FAMILIES) {
if (isNonNegativeInt(source[family])) leases[family] = source[family];
}
}
const lastAgedTurnId = typeof raw?.lastAgedTurnId === 'string' && raw.lastAgedTurnId.trim()
? raw.lastAgedTurnId.trim().slice(0, 200)
: null;
return { leases, lastAgedTurnId };
}
/**
* Age every existing lease by exactly one USER turn. Call this at most once
* per user turn — never per tool-round loop within a single turn, or a
* multi-step sequence would lose its own tools mid-flow — and never at all
* for a self-directed wake.
*
* A family already at 0 (its floor, set by a PRIOR aging pass) is dropped:
* that prior turn was its last one. Everything else decrements with a floor
* of 0 rather than being deleted immediately, so a family that just reached
* its floor THIS aging pass stays present — and therefore still exposed —
* for every remaining tool-round rebuild within the turn being aged, not
* only the first one.
*/
export function agePersistentMindToolActivation(leases) {
const normalized = normalizePersistentMindToolActivation({ leases }).leases;
const nextLeases = {};
for (const [family, turnsLeft] of Object.entries(normalized)) {
if (turnsLeft <= 0) continue;
nextLeases[family] = Math.max(turnsLeft - 1, 0);
}
return { leases: nextLeases };
}
/**
* Activate one or more families for a fresh `retentionTurns`-turn window.
* `retentionTurns <= 0` persists nothing — the family is still exposed for
* whatever turn calls this via the adapter's turn-local selection, without
* surviving into the next user or self-directed turn.
*/
export function activatePersistentMindToolActivationFamilies(leases, families, retentionTurns) {
const normalized = normalizePersistentMindToolActivation({ leases }).leases;
const next = { ...normalized };
if (isPositiveInt(retentionTurns)) {
for (const family of Array.isArray(families) ? families : []) {
if (isValidFamily(family)) next[family] = retentionTurns;
}
}
return next;
}
/**
* Renew a single family's lease back to the full retention window because a
* tool from it was just used — extending only the family actually exercised,
* never every family the turn happens to have activated.
*/
export function renewPersistentMindToolActivationFamily(leases, family, retentionTurns) {
return activatePersistentMindToolActivationFamilies(leases, [family], retentionTurns);
}
/** Clear one or more families (or all, when `families` is omitted/empty) — tools.deactivate. */
export function deactivatePersistentMindToolActivationFamilies(leases, families) {
const normalized = normalizePersistentMindToolActivation({ leases }).leases;
if (!Array.isArray(families) || families.length === 0) return {};
const next = { ...normalized };
for (const family of families) delete next[family];
return next;
}