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
/**
* Human action plans — the pure half.
*
* A *human action* is a step only the person can take (press Post, reply to
* people, upload a file), scheduled for a time and carried as a Brain thread so
* it shows up in Review Hub › Actions and the Open Threads widget like any other
* commitment. This module owns the request shape, how a step becomes a thread's
* next action + markdown notes, and when a step's reminder should fire. The
* service (`services/humanActions.js`) writes the threads; the reminder clock
* (`services/humanActionReminders.js`) fires one notification per due step.
*/
import { z } from 'zod';
import { THREAD_PRIORITIES, isTerminalThreadStatus } from './brainThreads.js';
export const HUMAN_ACTION_TAG = 'human-action';
export const HUMAN_ACTION_SOURCE = 'human-action';
export const HUMAN_ACTION_PLAN_TAG_PREFIX = 'plan:';
// A step that came due while the server was down still gets its reminder when
// it boots, but not one from last month: past this, the row in Actions is the
// reminder.
export const HUMAN_ACTION_CATCH_UP_MS = 24 * 60 * 60 * 1000;
// Node timers run off libuv's cached clock and can fire a millisecond or so
// before `Date.now()` reaches the due time; a step this close counts as due.
export const HUMAN_ACTION_EARLY_FIRE_MS = 1000;
export const HUMAN_ACTION_NOTES_MAX = 20000;
const planKey = z.string().trim().min(1).max(40)
.regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, 'planKey must be a lowercase dash slug');
export const humanActionStepSchema = z.object({
title: z.string().trim().min(1).max(200),
// When the person should do it. An offset is required so "18:00" is never
// silently read as UTC.
dueAt: z.string().datetime({ offset: true }),
// Explicit, ordered instructions. The first is the thread's next action.
instructions: z.array(z.string().trim().min(1).max(500)).min(1).max(20),
// Ready-to-paste text (a caption, a reply), each with a label saying where it goes.
content: z.array(z.object({
label: z.string().trim().min(1).max(100),
text: z.string().trim().min(1).max(5000),
}).strict()).max(10).optional().default([]),
links: z.array(z.object({
label: z.string().trim().max(200).optional().default(''),
url: z.string().trim().url().max(2000).regex(/^https?:\/\//i, 'links must be http(s)'),
}).strict()).max(10).optional().default([]),
priority: z.enum(THREAD_PRIORITIES).optional().default('normal'),
}).strict();
export const humanActionPlanSchema = z.object({
// Stable id for the plan, so planning again replaces its open steps instead
// of stacking a second copy of every reminder.
planKey,
title: z.string().trim().min(1).max(120),
steps: z.array(humanActionStepSchema).min(1).max(30),
}).strict().superRefine((plan, ctx) => {
// Thread notes are capped; reject a step that would not fit rather than cut it
// (a cut can drop a fenced block's closing fence or accepted instructions).
plan.steps.forEach((step, i) => {
if (buildHumanActionNotes(step, { planTitle: plan.title }).length > HUMAN_ACTION_NOTES_MAX) {
ctx.addIssue({ code: "custom", path: ["steps", i], message: `step notes exceed ${HUMAN_ACTION_NOTES_MAX} characters; shorten its instructions or content` });
}
});
});
export const humanActionPlanTag = (key) => `${HUMAN_ACTION_PLAN_TAG_PREFIX}${key}`;
/** A fence longer than any backtick run in `text`, so pasted code can't close it early. */
function fenceFor(text) {
const longest = Math.max(0, ...(String(text).match(/`+/g) || []).map((run) => run.length));
return '`'.repeat(Math.max(3, longest + 1));
}
/**
* The thread notes for one step: numbered instructions, then each piece of
* ready-to-paste content in its own fenced block (the Threads drawer offers a
* Copy button per block), then links.
*/
export function buildHumanActionNotes(step, { planTitle = '' } = {}) {
const parts = [];
if (planTitle) parts.push(`Part of **${planTitle}**.`);
parts.push(step.instructions.map((line, i) => `${i + 1}. ${line}`).join('\n'));
if (step.content?.length) {
parts.push('## Ready to paste');
for (const { label, text } of step.content) {
const fence = fenceFor(text);
parts.push(`**${label}**\n${fence}text\n${text}\n${fence}`);
}
}
if (step.links?.length) {
parts.push('## Links');
parts.push(step.links.map(({ label, url }) => `- [${label || url}](${url})`).join('\n'));
}
return parts.join('\n\n');
}
/** The Brain thread a step becomes (the writable fields; the service adds `source`). */
export function humanActionThreadFields(step, plan) {
return {
title: step.title,
status: 'open',
priority: step.priority || 'normal',
nextAction: step.instructions[0].slice(0, 500),
notes: buildHumanActionNotes(step, { planTitle: plan.title }),
dueAt: new Date(step.dueAt).toISOString(),
tags: [HUMAN_ACTION_TAG, humanActionPlanTag(plan.planKey)],
pinned: false,
waitingOn: '',
refs: (step.links || []).map(({ label, url }) => ({ kind: 'url', id: url, label: (label || url).slice(0, 300) })),
};
}
export const isHumanActionThread = (thread) => Array.isArray(thread?.tags) && thread.tags.includes(HUMAN_ACTION_TAG);
/**
* What the reminder clock should do with one thread right now:
* - `null` — nothing (not a human action, finished, undated, already reminded
* for this due time, or due too long ago to be worth a ping)
* - `{ fire: true }` — due now (or came due recently while PortOS was down)
* - `{ delayMs }` — arm a timer for the due time
*
* `remindedFor` holds the `dueAt` a reminder was sent for, so moving the due
* time re-arms it while a restart never repeats it.
*/
export function humanActionReminderDecision(thread, now = Date.now()) {
if (!isHumanActionThread(thread) || isTerminalThreadStatus(thread.status) || thread.status === 'someday') return null;
const due = Date.parse(thread.dueAt);
if (!Number.isFinite(due)) return null;
if (thread.remindedFor === thread.dueAt) return null;
if (due - now > HUMAN_ACTION_EARLY_FIRE_MS) return { delayMs: due - now };
return now - due <= HUMAN_ACTION_CATCH_UP_MS ? { fire: true } : null;
}