@namzu/sdk 27.1.0 → 28.0.0

package/src/manager/topic/lifecycle.ts

@@ -0,0 +1,235 @@
+/**
+ * TopicManager — thin orchestrator over {@link TopicStore} and
+ * {@link SessionStore}.
+ *
+ * Owns user-facing lifecycle operations on the Topic layer plus the
+ * archive-gate contract enforced at session-creation ingress sites.
+ *
+ * Phase 2.6 wired `TopicManager.requireOpen` into three ingress paths:
+ *   - {@link AgentManager.provisionSpawn} (child session creation)
+ *   - `executeSingleHandoff` (recipient session creation)
+ *   - `executeBroadcastHandoff` (N recipient sessions per fan-out)
+ * Those call sites depend on this manager, so the one-method indirection
+ * stopped being "structural overhead" the moment archive/delete needed the
+ * session-presence cross-check anyway.
+ *
+ * Archive + delete require cross-store preconditions (session-presence
+ * checks) — enforced here where both stores are in scope. The stores
+ * themselves stay unaware of each other's layout (Convention #0), which is
+ * why the gate lives at the manager layer rather than as a universal store
+ * interceptor (see `archive` JSDoc for the direct-store-bypass boundary).
+ *
+ * NZ-TOPIC-01 renamed this class from `ThreadManager` (moved from
+ * `manager/thread/lifecycle.ts`). NZ-TOPIC-04 deleted the `ThreadManager`
+ * alias entirely (see AGENTS.md's deprecate-before-remove note in the
+ * changeset for why a major, not a minor, was the right call here) — the
+ * class only lives under `TopicManager` now. NZ-TOPIC-03 renamed the
+ * `threadId` parameter on every method below to `topicId` — the FK-field
+ * rename that release deliberately deferred, now landed with its own data
+ * migration in `store/session/disk.ts`. `threadStore` (a DI dependency,
+ * not the FK) stayed `topicStore` from that same release. The thrown
+ * error classes (`ThreadClosedError`/`ThreadNotEmptyError`) are STILL
+ * unchanged in name, and so is their `details.threadId` field's NAME —
+ * `session/errors.ts` remains deliberately out of scope for the class and
+ * field renames (a clean follow-up), though NZ-TOPIC-04 did narrow the
+ * TYPE backing that field from `ThreadId` to `TopicId` since the former no
+ * longer exists. Constructing one from a `topicId` local below therefore
+ * still spells the key out (`{ threadId: topicId, ... }`) rather than
+ * using shorthand.
+ */
+
+import {
+	THREAD_NOT_EMPTY_SAMPLE_LIMIT,
+	ThreadClosedError,
+	ThreadNotEmptyError,
+} from '../../session/errors.js'
+import type { TenantId } from '../../types/ids/index.js'
+import type { Session, SessionStatus } from '../../types/session/entity.js'
+import type { ProjectId, TopicId } from '../../types/session/ids.js'
+import type { SessionStore } from '../../types/session/store.js'
+import type { Topic } from '../../types/topic/entity.js'
+import type { CreateTopicParams, TopicStore } from '../../types/topic/store.js'
+
+export interface TopicManagerDeps {
+	readonly topicStore: TopicStore
+	readonly sessionStore: SessionStore
+}
+
+/**
+ * Session statuses that block Topic archival. A session in any of these
+ * states has live work in-flight (mid-run, mid-handoff, blocked on human
+ * input, or orchestrating a broadcast merge) — freezing the Topic while any
+ * of them are active would strand resumable work.
+ *
+ * `idle`, `failed`, and `archived` are archival-compatible: they are
+ * quiescent or already-terminal, so a newly-frozen Topic can safely contain
+ * them. This list mirrors the `SessionStatus` discriminants that represent
+ * "not-yet-done" work (session-hierarchy.md §5.1).
+ */
+const ARCHIVAL_BLOCKING_STATUSES: ReadonlySet<SessionStatus> = new Set([
+	'active',
+	'locked',
+	'awaiting_hitl',
+	'awaiting_merge',
+])
+
+export class TopicManager {
+	private readonly deps: TopicManagerDeps
+
+	constructor(deps: TopicManagerDeps) {
+		this.deps = deps
+	}
+
+	/** Persist a new Topic. Thin passthrough for uniformity at the manager surface. */
+	create(params: CreateTopicParams, tenantId: TenantId): Promise<Topic> {
+		return this.deps.topicStore.createTopic(params, tenantId)
+	}
+
+	/** Read a Topic by id; returns `null` when absent for the tenant. */
+	get(topicId: TopicId, tenantId: TenantId): Promise<Topic | null> {
+		return this.deps.topicStore.getTopic(topicId, tenantId)
+	}
+
+	/**
+	 * CAS update on a Topic. Propagates {@link import('../../session/errors.js').StaleThreadError}
+	 * from the store on `ownerVersion` mismatch — callers re-read, re-apply,
+	 * and retry.
+	 */
+	update(topic: Topic, tenantId: TenantId): Promise<void> {
+		return this.deps.topicStore.updateTopic(topic, tenantId)
+	}
+
+	/** List Topics under a Project, ordered by `createdAt` ascending. */
+	list(projectId: ProjectId, tenantId: TenantId): Promise<readonly Topic[]> {
+		return this.deps.topicStore.listTopics(projectId, tenantId)
+	}
+
+	/**
+	 * Load a Topic and assert it is in `'open'` state. Used by the spawn path
+	 * as a precondition — a SubSession cannot be created under an archived
+	 * Topic. Throws on absence and on archival; returns the loaded Topic on
+	 * success so callers can avoid the second round-trip.
+	 *
+	 * Convention #5: deny-by-default. A missing Topic is a hard error, not a
+	 * silent "assume archived".
+	 */
+	async requireOpen(topicId: TopicId, tenantId: TenantId): Promise<Topic> {
+		const topic = await this.deps.topicStore.getTopic(topicId, tenantId)
+		if (!topic) {
+			throw new Error(`Topic ${topicId} not found`)
+		}
+		if (topic.status === 'archived') {
+			throw new ThreadClosedError({ threadId: topicId, op: 'require-open' })
+		}
+		return topic
+	}
+
+	/**
+	 * Flip a Topic to `'archived'` via CAS on {@link Topic.ownerVersion}.
+	 *
+	 * Preconditions (checked in order):
+	 *   1. Topic exists for the tenant (throws on absence).
+	 *   2. No attached Session is in a non-terminal state (see
+	 *      {@link ARCHIVAL_BLOCKING_STATUSES}). The presence check runs
+	 *      **before** the idempotent-archive short-circuit so that an already
+	 *      archived topic harboring a live session still surfaces as
+	 *      {@link ThreadNotEmptyError} rather than a silent success.
+	 *   3. If the topic is already `'archived'` the method short-circuits
+	 *      without an `updateTopic` write (idempotent re-archival). The
+	 *      returned record reflects the current persisted state.
+	 *
+	 * On a fresh archive transition the underlying
+	 * {@link TopicStore.updateTopic} call commits with `ownerVersion + 1`.
+	 * A {@link import('../../session/errors.js').StaleThreadError} from a
+	 * concurrent writer propagates unchanged — the caller is expected to
+	 * re-read + retry (mirrors the `updateTopic` contract).
+	 *
+	 * Gate scope (Phase 2.6): `TopicManager.requireOpen` is wired into
+	 * `AgentManager.provisionSpawn` and both handoff flows, so the production
+	 * ingress paths cannot attach new sessions under an archived topic.
+	 * `SessionStore.createSession` / `updateSession` remain public and
+	 * ungated at the store layer — a direct caller can still mutate a
+	 * session after archival (the store has no `TopicStore` handle by
+	 * design; cross-store awareness lives in the manager). The defensive
+	 * re-check above catches a smuggled live session on a subsequent
+	 * archive call, but does not prevent the direct-store write from
+	 * landing. That's an acceptable boundary — kernel callers must go
+	 * through the ingress paths; direct store consumers are out of scope
+	 * for the archive invariant.
+	 */
+	async archive(topicId: TopicId, tenantId: TenantId): Promise<Topic> {
+		const topic = await this.deps.topicStore.getTopic(topicId, tenantId)
+		if (!topic) {
+			throw new Error(`Topic ${topicId} not found`)
+		}
+
+		// Always enforce the blocking-session invariant — even on re-archival.
+		// If the topic is already archived but somehow gained a live session
+		// (direct store mutation, concurrent spawn before a write-barrier
+		// existed), surfacing that via ThreadNotEmptyError is more useful to
+		// operators than a silent idempotent success.
+		const sessions = await this.deps.sessionStore.listSessionsByTopic(topicId, tenantId)
+		const blocking = sessions.filter((s) => ARCHIVAL_BLOCKING_STATUSES.has(s.status))
+		if (blocking.length > 0) {
+			throw new ThreadNotEmptyError({
+				threadId: topicId,
+				tenantId,
+				op: 'archive',
+				blockingSessions: summarizeBlocking(blocking),
+				totalBlockingSessions: blocking.length,
+			})
+		}
+
+		if (topic.status === 'archived') {
+			// Idempotent: already archived, no live sessions attached. Skip the
+			// write (updateTopic would still bump ownerVersion for no semantic
+			// change).
+			return topic
+		}
+
+		const next: Topic = { ...topic, status: 'archived' }
+		await this.deps.topicStore.updateTopic(next, tenantId)
+		// updateTopic advances ownerVersion + updatedAt; re-read so the returned
+		// record reflects the persisted state (callers rely on version monotonicity).
+		const reloaded = await this.deps.topicStore.getTopic(topicId, tenantId)
+		if (!reloaded) {
+			throw new Error(`Topic ${topicId} vanished between archive and read-back`)
+		}
+		return reloaded
+	}
+
+	/**
+	 * Hard-delete a Topic record. Rejects with {@link ThreadNotEmptyError}
+	 * (`op: 'delete'`) when ANY Session still references the Topic —
+	 * deletion is stricter than archival, which tolerates quiescent sessions.
+	 * Callers must first delete or archive-and-tombstone every attached
+	 * session (via {@link SessionStore.deleteSession}) before invoking.
+	 *
+	 * The session scan runs unconditionally, so orphaned sessions pointing at
+	 * a missing topic are still detected and reject the delete. Idempotent
+	 * for genuinely absent topics (no sessions, no topic record) — missing
+	 * topic + empty session list is a no-op at the store layer. Convention
+	 * #5: deny-by-default; no implicit cascade into SessionStore.
+	 */
+	async delete(topicId: TopicId, tenantId: TenantId): Promise<void> {
+		const sessions = await this.deps.sessionStore.listSessionsByTopic(topicId, tenantId)
+		if (sessions.length > 0) {
+			throw new ThreadNotEmptyError({
+				threadId: topicId,
+				tenantId,
+				op: 'delete',
+				blockingSessions: summarizeBlocking(sessions),
+				totalBlockingSessions: sessions.length,
+			})
+		}
+		await this.deps.topicStore.deleteTopic(topicId, tenantId)
+	}
+}
+
+function summarizeBlocking(
+	sessions: readonly Session[],
+): ReadonlyArray<{ sessionId: Session['id']; status: SessionStatus }> {
+	return sessions
+		.slice(0, THREAD_NOT_EMPTY_SAMPLE_LIMIT)
+		.map((s) => ({ sessionId: s.id, status: s.status }))
+}

package/src/manager/topic/objective.ts

@@ -0,0 +1,203 @@
+import { ObjectiveExhaustedError, type TopicObjectiveStore } from '../../store/topic/objective.js'
+import type { TenantId } from '../../types/ids/index.js'
+import type {
+	ObjectiveAdvanceResult,
+	ObjectiveRoundVerdict,
+	TopicObjective,
+} from '../../types/topic/objective.js'
+
+/**
+ * One round of an objective, from debit to verdict.
+ *
+ * The store holds the rules and the manager holds the sequence, so a host
+ * writes the work and not the bookkeeping. Getting that sequence wrong is
+ * how a cap stops capping: run the round first and a crash costs nothing,
+ * so an objective failing every round runs forever.
+ */
+
+export interface AdvanceObjectiveParams {
+	readonly id: string
+	readonly tenantId: TenantId
+	/**
+	 * The work. Its return value is the verdict; a throw is `runner_failed`.
+	 *
+	 * It receives the record with the round ALREADY debited, so a runner
+	 * that wants to know which round it is reads the same number the cap
+	 * will be compared against.
+	 */
+	readonly round: (objective: TopicObjective) => Promise<ObjectiveRoundVerdict>
+}
+
+/** Advance one round, or say why it did not. */
+export async function advanceObjective(
+	store: TopicObjectiveStore,
+	params: AdvanceObjectiveParams,
+): Promise<ObjectiveAdvanceResult> {
+	const current = await store.getObjective(params.id, params.tenantId)
+	if (!current) throw new Error(`No objective ${params.id}.`)
+
+	if (current.phase !== 'active') {
+		// A refusal rather than a throw. "Paused" and "already complete" are
+		// ordinary answers to "is there more to do" — a caller polling a set
+		// of objectives should not have to catch an exception per finished
+		// one to find the running ones.
+		return { kind: 'refused', reason: `Objective is ${current.phase}.`, phase: current.phase }
+	}
+
+	let debited: TopicObjective
+	try {
+		debited = await store.beginRound(params.id, params.tenantId, { revision: current.revision })
+	} catch (error) {
+		if (error instanceof ObjectiveExhaustedError) {
+			// `beginRound` has already written the `blocked` phase, so this
+			// reads the record back rather than describing it — the refusal a
+			// caller sees and the record a later reader finds are then the same
+			// fact rather than two statements that could disagree.
+			const blocked = await store.getObjective(params.id, params.tenantId)
+			return {
+				kind: 'refused',
+				reason: blocked?.blockedReason?.message ?? error.message,
+				phase: blocked?.phase ?? 'blocked',
+			}
+		}
+		throw error
+	}
+
+	let verdict: ObjectiveRoundVerdict
+	try {
+		verdict = await params.round(debited)
+	} catch (error) {
+		// Blocked, not lost. A runner that threw has left an objective whose
+		// round is spent and whose state would otherwise still say `active`,
+		// and the next poll would spend another round the same way.
+		const settled = await store.settleRound(
+			params.id,
+			params.tenantId,
+			{
+				phase: 'blocked',
+				blockedReason: {
+					code: 'runner_failed',
+					message: error instanceof Error ? error.message : String(error),
+				},
+			},
+			{ revision: debited.revision },
+		)
+		return { kind: 'advanced', objective: settled }
+	}
+
+	const settled = await store.settleRound(params.id, params.tenantId, verdict, {
+		revision: debited.revision,
+	})
+	return { kind: 'advanced', objective: settled }
+}
+
+export interface DriveObjectiveParams extends AdvanceObjectiveParams {
+	/**
+	 * Stop after this many rounds in THIS call.
+	 *
+	 * Separate from the objective's own `maxRounds`, which is durable and
+	 * spans every call. This one bounds a single drive so a host can hand
+	 * back to its caller — an objective with 200 rounds left should not
+	 * decide how long one HTTP request takes.
+	 *
+	 * Omitted, the bound is the objective's OWN remaining rounds rather than
+	 * no bound at all. See `driveObjective`.
+	 */
+	readonly maxRoundsThisCall?: number
+
+	/**
+	 * Checked between rounds, never mid-round.
+	 *
+	 * The interrupt a human actually gets: the round in flight finishes and
+	 * writes its verdict, and the next one does not start. Aborting mid-round
+	 * would leave a round debited whose work was thrown away, which is the
+	 * one state the debit-first rule exists to prevent.
+	 */
+	readonly signal?: AbortSignal
+}
+
+/** A drive that ran a round and got no round out of it. */
+export class ObjectiveNotProgressingError extends Error {
+	readonly details: { id: string; roundsStarted: number }
+
+	constructor(details: { id: string; roundsStarted: number }) {
+		super(
+			`Objective ${details.id} ran a round and roundsStarted stayed at ${details.roundsStarted}; refusing to loop.`,
+		)
+		this.name = 'ObjectiveNotProgressingError'
+		this.details = details
+	}
+}
+
+/**
+ * Round after round until the objective stops asking for one.
+ *
+ * **The default bound is the objective's own remaining rounds, not
+ * infinity.** An unbounded default was written here first and a mutation
+ * test caught what it costs: break the round debit and this becomes a hot
+ * loop that no timeout can interrupt, because with an in-memory store every
+ * `await` in it resolves as a microtask and the event loop never reaches a
+ * timer. It ran twelve minutes at 100% CPU against a five-second test
+ * timeout that could never fire. Deriving the bound from `maxRounds` makes
+ * the loop finite by construction, from a number the record already has to
+ * carry.
+ *
+ * The progress check below is the second half of the same lesson: a bound
+ * stops the spin, but it stops it silently after a hundred wasted rounds.
+ */
+export async function driveObjective(
+	store: TopicObjectiveStore,
+	params: DriveObjectiveParams,
+): Promise<TopicObjective> {
+	const start = await store.getObjective(params.id, params.tenantId)
+	if (!start) throw new Error(`No objective ${params.id}.`)
+
+	const remaining = Math.max(0, start.maxRounds - start.roundsStarted)
+	// `remaining + 1`, and the `+ 1` is the point: it is the iteration that
+	// asks for the round past the cap and is refused, which is what WRITES
+	// the `blocked` record. Stopping at `remaining` would leave an objective
+	// out of rounds still reading `active` — a state whose only remaining
+	// move is to be blocked, described as if it could still run.
+	//
+	// The refused iteration costs nothing; `beginRound` turns it away before
+	// the round callback is reached.
+	//
+	// A caller's own budget is the tighter bound when it gives one, and the
+	// `Infinity` below never survives the `min` — that is what keeps this
+	// finite by construction rather than by the caller remembering.
+	const budget = Math.min(params.maxRoundsThisCall ?? Number.POSITIVE_INFINITY, remaining + 1)
+
+	let rounds = 0
+	let lastRoundsStarted = start.roundsStarted
+	while (rounds < budget) {
+		if (params.signal?.aborted) break
+		const result = await advanceObjective(store, params)
+		rounds += 1
+		if (result.kind === 'refused') break
+
+		// A round that did not advance the counter means the debit is broken,
+		// and every further iteration would repeat it. Named and thrown rather
+		// than left to the budget, so the failure says what it is instead of
+		// looking like an objective that quietly ran out.
+		if (result.objective.roundsStarted <= lastRoundsStarted) {
+			throw new ObjectiveNotProgressingError({
+				id: params.id,
+				roundsStarted: result.objective.roundsStarted,
+			})
+		}
+		lastRoundsStarted = result.objective.roundsStarted
+
+		// An early exit, NOT a correctness guard, and it survives mutation for
+		// that reason: delete it and the next iteration calls
+		// `advanceObjective`, which reads the terminal phase and refuses, and
+		// the drive ends in the same state having done one extra store read.
+		// The refusal above is what makes stopping correct. This line only
+		// makes it cheap — which against the disk store is a real file read
+		// per completed drive, so it stays.
+		if (result.objective.phase !== 'active') break
+	}
+
+	const final = await store.getObjective(params.id, params.tenantId)
+	if (!final) throw new Error(`No objective ${params.id}.`)
+	return final
+}

package/src/persona/assembler.ts

@@ -1,5 +1,5 @@
 import type { AgentPersona, OutputDiscipline } from '../types/persona/index.js'
-import type { Skill } from '../types/skills/index.js'
+import { type Skill, isInvocableBy } from '../types/skills/index.js'
 
 export function assembleSystemPrompt(persona: AgentPersona, skills?: Skill[]): string {
 	const sections: string[] = []
@@ -46,7 +46,14 @@ export function assembleSystemPrompt(persona: AgentPersona, skills?: Skill[]): s
 export function renderSkillsSection(skills?: Skill[]): string | null {
 	if (!skills || skills.length === 0) return null
 
-	const available = skills
+	// Only what the MODEL may invoke. An operator-only skill listed here is
+	// something the model will read as available and attempt — "collect a
+	// support bundle", "rotate the deploy key" — and the attempt is the
+	// failure, not the listing.
+	const forModel = skills.filter((skill) => isInvocableBy(skill, 'model'))
+	if (forModel.length === 0) return null
+
+	const available = forModel
 		.map((s) => {
 			const lines = [
 				'<skill>',
@@ -68,7 +75,11 @@ export function renderSkillsSection(skills?: Skill[]): string | null {
 		})
 		.join('\n')
 
-	const loadedSkills = skills.filter((s) => s.body)
+	// `forModel`, not `skills`: a loaded operator-only skill would otherwise
+	// have its whole BODY pasted into the model's prompt while being absent
+	// from the manifest above — the worst of both, since the model gets the
+	// instructions and no listing that would let it reason about them.
+	const loadedSkills = forModel.filter((s) => s.body)
 	const sections = [
 		`## Available Skills\nThe following block is a manifest, not the full skill content. Skill metadata is always visible; SKILL.md bodies are loaded only when the user's task matches the skill description.\n\n<available_skills>\n${available}\n</available_skills>\n\nSkill usage protocol:\n- Plain questions do not require a skill.\n- When a matching skill is already listed under Loaded Skills, apply its loaded instructions.\n- When a matching skill is not loaded and the runtime exposes filesystem or skill-loading tools, read the SKILL.md at its <location> before writing code, creating files, running shell commands for that workflow, or calling mutation tools guided by the skill.\n- Do not claim to have read a SKILL.md until its content is actually present in the prompt or returned by a tool.\n- Tool schemas and runtime permissions remain authoritative; skills provide guidance, not hidden tools.`,
 	]