@minionry/minion 0.7.36

package/dist/server/services/schedule/scheduler.js

@@ -0,0 +1,310 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { join } from 'node:path';
+import { PlanExecutor } from '../plan/executor.js';
+import { resolvePmDir } from '../plan/parser.js';
+import { wireExecutorEvents } from '../websocket/plan-execution-handlers.js';
+import { schedulerCache } from '../websocket/plan-helpers.js';
+import { bootstrapRun } from './run-bootstrap.js';
+import { ScheduleStore } from './schedule-store.js';
+export const SCHEDULER_TICK_MS = 30_000;
+export const SCHEDULE_ONCE_GRACE_MS = 15 * 60_000;
+export const CONTINUOUS_MIN_SPACING_MS = 60_000;
+export const CONTINUOUS_MAX_BACKOFF_MS = 30 * 60_000;
+export function continuousDelayMs(consecutiveEmptyRuns) {
+    const empties = Math.max(0, Math.floor(consecutiveEmptyRuns));
+    return Math.min(CONTINUOUS_MIN_SPACING_MS * 2 ** empties, CONTINUOUS_MAX_BACKOFF_MS);
+}
+export class ScheduledRunRegistry {
+    runs = new Map();
+    get(scheduleId) {
+        return this.runs.get(scheduleId);
+    }
+    has(scheduleId) {
+        return this.runs.has(scheduleId);
+    }
+    set(scheduleId, run) {
+        this.runs.set(scheduleId, run);
+    }
+    delete(scheduleId) {
+        this.runs.delete(scheduleId);
+    }
+    activeIds() {
+        return Array.from(this.runs.keys());
+    }
+    snapshotValues() {
+        return Array.from(this.runs.values());
+    }
+    reset() {
+        for (const run of this.runs.values()) {
+            try {
+                run.settled = true;
+                run.executor.removeAllListeners();
+                run.executor.stop();
+            }
+            catch {
+            }
+        }
+        this.runs.clear();
+    }
+}
+export class SchedulerEngine {
+    workingDir;
+    runs = new ScheduledRunRegistry();
+    ctx;
+    deps;
+    tickIntervalMs;
+    timer = null;
+    store = null;
+    constructor(workingDir, ctx, deps = {}) {
+        this.workingDir = workingDir;
+        this.ctx = ctx;
+        this.deps = deps;
+        this.tickIntervalMs = deps.tickIntervalMs ?? SCHEDULER_TICK_MS;
+    }
+    getStore() {
+        return this.store;
+    }
+    isRunning() {
+        return this.timer !== null;
+    }
+    start() {
+        if (this.timer)
+            return;
+        if (!resolvePmDir(this.workingDir))
+            return;
+        this.store = new ScheduleStore(this.workingDir);
+        this.recoverMissedFires();
+        this.tick();
+        this.timer = setInterval(() => this.tick(), this.tickIntervalMs);
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.runs.reset();
+        this.store = null;
+    }
+    tick() {
+        const store = this.store;
+        if (!store)
+            return;
+        const now = Date.now();
+        for (const record of store.list()) {
+            if (!record.enabled)
+                continue;
+            if (this.runs.has(record.id)) {
+                if (record.timing.kind !== 'continuous' && this.isDue(record, now)) {
+                    this.recordSkippedOverlap(record, now);
+                }
+                continue;
+            }
+            if (!this.isDue(record, now))
+                continue;
+            this.fire(record, now);
+        }
+    }
+    isDue(record, now) {
+        if (record.timing.kind === 'continuous') {
+            if (record.nextFireAt)
+                return parseEpoch(record.nextFireAt) <= now;
+            const lastAt = record.lastFire ? parseEpoch(record.lastFire.at) : Number.NaN;
+            if (!Number.isFinite(lastAt))
+                return true;
+            return now - lastAt >= continuousDelayMs(record.consecutiveEmptyRuns);
+        }
+        if (!record.nextFireAt)
+            return false;
+        const at = parseEpoch(record.nextFireAt);
+        return Number.isFinite(at) && at <= now;
+    }
+    recoverMissedFires() {
+        const store = this.store;
+        if (!store)
+            return;
+        const now = Date.now();
+        for (const record of store.list()) {
+            if (!record.enabled)
+                continue;
+            if (record.timing.kind === 'once') {
+                this.recoverOnce(record, now);
+            }
+            else if (record.timing.kind === 'interval') {
+                this.recoverInterval(record, now);
+            }
+        }
+    }
+    recoverOnce(record, now) {
+        if (record.timing.kind !== 'once')
+            return;
+        const at = parseEpoch(record.timing.at);
+        if (!Number.isFinite(at) || at > now)
+            return;
+        if (now - at <= SCHEDULE_ONCE_GRACE_MS) {
+            this.fire(record, now);
+            return;
+        }
+        const store = this.store;
+        if (!store)
+            return;
+        store.recordFire(record.id, { at: new Date(now).toISOString(), status: 'missed', boardId: null, error: 'missed by more than the 15 minute grace window' }, null);
+        store.setEnabled(record.id, false);
+        this.broadcastSchedules();
+    }
+    recoverInterval(record, now) {
+        const next = record.nextFireAt ? parseEpoch(record.nextFireAt) : Number.NaN;
+        if (Number.isFinite(next) && next > now)
+            return;
+        this.fire(record, now);
+    }
+    fire(record, now) {
+        const store = this.store;
+        if (!store)
+            return;
+        const pmDir = resolvePmDir(this.workingDir);
+        if (!pmDir)
+            return;
+        const firedAt = new Date(now).toISOString();
+        const source = { kind: record.source.kind, durablePath: join(pmDir, record.source.path) };
+        let result;
+        try {
+            result = (this.deps.bootstrap ?? bootstrapRun)(this.workingDir, source, record.input, {
+                scheduleId: record.id,
+                broadcast: response => this.ctx.broadcastToAll(response),
+            });
+        }
+        catch (error) {
+            this.recordFailedFire(record, firedAt, errorMessage(error));
+            return;
+        }
+        store.recordFire(record.id, { at: firedAt, status: 'started', boardId: result.boardId }, this.nextFireAtAfterStart(record, now));
+        this.broadcastSchedules();
+        this.ctx.broadcastToAll({
+            type: 'planScheduleFired',
+            data: { scheduleId: record.id, boardId: result.boardId, firedAt },
+        });
+        this.startRun(record, result.boardId, now);
+    }
+    startRun(record, boardId, now) {
+        const executor = (this.deps.createExecutor ?? defaultCreateExecutor)(this.workingDir);
+        const run = { scheduleId: record.id, boardId, executor, startedAt: now, lastError: null, settled: false };
+        this.runs.set(record.id, run);
+        (this.deps.wireEvents ?? wireExecutorEvents)(executor, this.ctx, this.workingDir, boardId);
+        executor.on('error', (message) => {
+            run.lastError = errorMessage(message);
+            this.settle(run);
+        });
+        executor.on('complete', () => { this.settle(run); });
+        this.ctx.broadcastToAll({ type: 'planExecutionStarted', data: { status: 'executing', boardId } });
+        executor.startBoard(boardId).then(() => this.settle(run), (error) => {
+            run.lastError = errorMessage(error);
+            this.settle(run);
+        });
+    }
+    settle(run) {
+        if (run.settled)
+            return;
+        run.settled = true;
+        this.runs.delete(run.scheduleId);
+        const store = this.store;
+        const record = store?.get(run.scheduleId);
+        if (!store || !record)
+            return;
+        const issuesCompleted = safeIssuesCompleted(run.executor);
+        const productive = !run.lastError && issuesCompleted > 0;
+        const consecutiveEmptyRuns = productive ? 0 : record.consecutiveEmptyRuns + 1;
+        const status = run.lastError ? 'failed' : 'completed';
+        const error = run.lastError ?? (issuesCompleted === 0 ? 'run produced no issues' : undefined);
+        const now = Date.now();
+        store.recordFire(run.scheduleId, { at: new Date(now).toISOString(), status, boardId: run.boardId, ...(error ? { error } : {}) }, this.nextFireAtAfterSettle(record, now, consecutiveEmptyRuns), consecutiveEmptyRuns);
+        if (record.timing.kind === 'once')
+            store.setEnabled(run.scheduleId, false);
+        this.broadcastSchedules();
+    }
+    recordFailedFire(record, firedAt, error) {
+        const store = this.store;
+        if (!store)
+            return;
+        const consecutiveEmptyRuns = record.consecutiveEmptyRuns + 1;
+        const now = parseEpoch(firedAt);
+        const entry = { at: firedAt, status: 'failed', boardId: null, error };
+        store.recordFire(record.id, entry, this.nextFireAtAfterFailure(record, now, consecutiveEmptyRuns), consecutiveEmptyRuns);
+        if (record.timing.kind === 'once')
+            store.setEnabled(record.id, false);
+        this.broadcastSchedules();
+    }
+    recordSkippedOverlap(record, now) {
+        const store = this.store;
+        if (!store)
+            return;
+        store.recordFire(record.id, { at: new Date(now).toISOString(), status: 'skipped-overlap', boardId: null, error: 'previous run for this schedule is still in flight' }, this.nextFireAtAfterStart(record, now));
+        this.broadcastSchedules();
+    }
+    nextFireAtAfterStart(record, now) {
+        if (record.timing.kind === 'interval')
+            return new Date(now + record.timing.everyMs).toISOString();
+        return null;
+    }
+    nextFireAtAfterFailure(record, now, consecutiveEmptyRuns) {
+        if (record.timing.kind === 'once')
+            return null;
+        if (record.timing.kind === 'continuous') {
+            return new Date(now + continuousDelayMs(consecutiveEmptyRuns)).toISOString();
+        }
+        return new Date(now + record.timing.everyMs).toISOString();
+    }
+    nextFireAtAfterSettle(record, now, consecutiveEmptyRuns) {
+        if (record.timing.kind === 'once')
+            return null;
+        if (record.timing.kind === 'continuous') {
+            return new Date(now + continuousDelayMs(consecutiveEmptyRuns)).toISOString();
+        }
+        const store = this.store;
+        return store?.get(record.id)?.nextFireAt ?? new Date(now + record.timing.everyMs).toISOString();
+    }
+    broadcastSchedules() {
+        if (!this.store)
+            return;
+        this.ctx.broadcastToAll({ type: 'planSchedulesChanged', data: { schedules: this.store.list() } });
+    }
+}
+function defaultCreateExecutor(workingDir) {
+    return new PlanExecutor(workingDir);
+}
+function parseEpoch(iso) {
+    return Date.parse(iso);
+}
+function errorMessage(error) {
+    if (typeof error === 'string')
+        return error;
+    return error instanceof Error ? error.message : String(error);
+}
+function safeIssuesCompleted(executor) {
+    try {
+        return executor.getMetrics().issuesCompleted;
+    }
+    catch {
+        return 0;
+    }
+}
+export function getScheduler(workingDir, ctx, deps) {
+    let engine = schedulerCache.get(workingDir);
+    if (!engine) {
+        engine = new SchedulerEngine(workingDir, ctx, deps);
+        schedulerCache.set(workingDir, engine);
+    }
+    return engine;
+}
+export function stopAllSchedulers() {
+    for (const engine of schedulerCache.values()) {
+        try {
+            engine.stop();
+        }
+        catch {
+        }
+    }
+    schedulerCache.clear();
+}

package/dist/server/services/schedule/template-source.js

@@ -0,0 +1,97 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { validatePathWithinWorkingDir } from '../pathUtils.js';
+import { extractBoardArchive } from '../plan/board-archive.js';
+import { parseFrontMatter } from '../plan/parser-core.js';
+import { loadTemplate, validateTemplate } from '../plan/template-instantiator.js';
+export const MAX_SOURCE_ZIP_BYTES = 50 * 1024 * 1024;
+export class TemplateSourceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'TemplateSourceError';
+    }
+}
+function durableFileName(kind) {
+    return kind === 'template-json' ? 'template.json' : 'template.zip';
+}
+function resolveSourcePath(rawPath, workingDir) {
+    const validation = validatePathWithinWorkingDir(rawPath, workingDir);
+    if (!validation.valid) {
+        throw new TemplateSourceError('invalid_path', validation.error ?? 'Invalid source path');
+    }
+    if (!existsSync(validation.resolvedPath) || !statSync(validation.resolvedPath).isFile()) {
+        throw new TemplateSourceError('not_found', `Source file not found: ${rawPath}`);
+    }
+    return validation.resolvedPath;
+}
+function resolveTemplateJsonSource(resolvedPath) {
+    let template;
+    try {
+        template = loadTemplate(resolvedPath);
+    }
+    catch (err) {
+        throw new TemplateSourceError('invalid_template', err instanceof Error ? err.message : String(err));
+    }
+    const validation = validateTemplate(template);
+    if (!validation.valid) {
+        const summary = validation.errors.map(e => `${e.pointer ?? '<root>'}: ${e.message}`).join('; ');
+        throw new TemplateSourceError('invalid_template', `Template is invalid: ${summary}`);
+    }
+    return {
+        boardTitle: template.board.title,
+        issueCount: template.issues.length,
+        variables: template.variables ?? [],
+    };
+}
+function resolveBoardZipSource(resolvedPath) {
+    if (statSync(resolvedPath).size > MAX_SOURCE_ZIP_BYTES) {
+        throw new TemplateSourceError('too_large', 'Board archive exceeds the 50 MB limit');
+    }
+    let files;
+    try {
+        ({ files } = extractBoardArchive(readFileSync(resolvedPath)));
+    }
+    catch (err) {
+        throw new TemplateSourceError('invalid_archive', err instanceof Error ? err.message : String(err));
+    }
+    const boardMd = files.get('board.md');
+    const { frontMatter } = parseFrontMatter(boardMd ? Buffer.from(boardMd).toString('utf-8') : '');
+    const boardTitle = typeof frontMatter.title === 'string' && frontMatter.title ? frontMatter.title : 'Imported board';
+    const issueCount = [...files.keys()].filter(p => p.startsWith('backlog/') && p.endsWith('.md')).length;
+    return { boardTitle, issueCount };
+}
+export function previewTemplateSource(options) {
+    const { workingDir, source } = options;
+    const resolvedPath = resolveSourcePath(source.path, workingDir);
+    if (source.kind === 'template-json') {
+        const { boardTitle, issueCount, variables } = resolveTemplateJsonSource(resolvedPath);
+        return { kind: 'template-json', boardTitle, issueCount, variables };
+    }
+    const { boardTitle, issueCount } = resolveBoardZipSource(resolvedPath);
+    return { kind: 'board-zip', boardTitle, issueCount, variables: [] };
+}
+export function resolveTemplateSource(options) {
+    const { workingDir, pmDir, scheduleId, source } = options;
+    const resolvedPath = resolveSourcePath(source.path, workingDir);
+    const durableDir = join(pmDir, 'schedules', scheduleId);
+    const durablePath = join(durableDir, durableFileName(source.kind));
+    const needsCopy = resolvedPath !== durablePath;
+    if (source.kind === 'template-json') {
+        const { boardTitle, issueCount, variables } = resolveTemplateJsonSource(resolvedPath);
+        if (needsCopy) {
+            mkdirSync(durableDir, { recursive: true });
+            writeFileSync(durablePath, readFileSync(resolvedPath, 'utf-8'), 'utf-8');
+        }
+        return { kind: 'template-json', durablePath, boardTitle, issueCount, variables };
+    }
+    const { boardTitle, issueCount } = resolveBoardZipSource(resolvedPath);
+    if (needsCopy) {
+        mkdirSync(durableDir, { recursive: true });
+        writeFileSync(durablePath, readFileSync(resolvedPath));
+    }
+    return { kind: 'board-zip', durablePath, boardTitle, issueCount, variables: [] };
+}

package/dist/server/services/sdk/agent-sessions.js

@@ -0,0 +1,264 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { isImageFile, readFileContent } from '../websocket/file-utils.js';
+import { logAppAudit } from './audit.js';
+import { resolveGuardWithRoot } from './files-transfer.js';
+import { SdkMethodError } from './registry.js';
+export const MAX_PROMPT_ATTACHMENTS = 10;
+function resolveAttachments(args, refs) {
+    if (refs.length > MAX_PROMPT_ATTACHMENTS) {
+        throw new SdkMethodError('BAD_REQUEST', `agents.sessions.prompt: at most ${MAX_PROMPT_ATTACHMENTS} attachments per prompt`);
+    }
+    return refs.map((ref) => {
+        const { resolvedPath } = resolveGuardWithRoot(args, ref.path);
+        const result = readFileContent(resolvedPath, args.workingDir);
+        if (result.error) {
+            throw new SdkMethodError('BAD_REQUEST', `agents.sessions.prompt: attachment '${ref.path}': ${result.error}`);
+        }
+        return {
+            fileName: result.fileName,
+            filePath: resolvedPath,
+            content: result.content,
+            isImage: Boolean(result.isImage) && isImageFile(resolvedPath),
+            mimeType: result.mimeType,
+        };
+    });
+}
+let sessionHost = null;
+export function setSdkSessionHost(host) {
+    sessionHost = host;
+}
+export function resetSdkSessionHost() {
+    sessionHost = null;
+}
+function requireHost() {
+    if (!sessionHost) {
+        throw new SdkMethodError('INTERNAL', 'agents.sessions host is not wired — the WebSocket handler installs it at startup');
+    }
+    return sessionHost;
+}
+function paramsObject(params) {
+    return typeof params === 'object' && params !== null && !Array.isArray(params) ? params : {};
+}
+function parseSessionIdParams(params, method) {
+    const raw = paramsObject(params);
+    if (typeof raw.sessionId !== 'string' || raw.sessionId.trim() === '') {
+        throw new SdkMethodError('BAD_REQUEST', `${method} requires params { sessionId }`);
+    }
+    return raw.sessionId;
+}
+function parseCreateParams(params) {
+    if (params === undefined || params === null)
+        return {};
+    const raw = paramsObject(params);
+    if (raw.name !== undefined && typeof raw.name !== 'string') {
+        throw new SdkMethodError('BAD_REQUEST', 'agents.sessions.create name must be a string when present');
+    }
+    return { name: raw.name };
+}
+function parseRenameParams(params) {
+    const raw = paramsObject(params);
+    if (typeof raw.sessionId !== 'string' || raw.sessionId.trim() === '') {
+        throw new SdkMethodError('BAD_REQUEST', 'agents.sessions.rename requires params { sessionId, name }');
+    }
+    if (typeof raw.name !== 'string' || raw.name.trim() === '') {
+        throw new SdkMethodError('BAD_REQUEST', 'agents.sessions.rename requires a non-empty string name');
+    }
+    return { sessionId: raw.sessionId, name: raw.name };
+}
+function parseApproveParams(params) {
+    const raw = paramsObject(params);
+    if (typeof raw.sessionId !== 'string' || raw.sessionId.trim() === '') {
+        throw new SdkMethodError('BAD_REQUEST', 'agents.sessions.approve requires params { sessionId, approved }');
+    }
+    if (typeof raw.approved !== 'boolean') {
+        throw new SdkMethodError('BAD_REQUEST', 'agents.sessions.approve requires a boolean approved');
+    }
+    return { sessionId: raw.sessionId, approved: raw.approved };
+}
+function parseAnswerQuestionParams(params) {
+    const raw = paramsObject(params);
+    if (typeof raw.sessionId !== 'string' || raw.sessionId.trim() === '') {
+        throw new SdkMethodError('BAD_REQUEST', 'agents.sessions.answerQuestion requires params { sessionId, toolUseId, answers }');
+    }
+    if (typeof raw.toolUseId !== 'string' || raw.toolUseId.trim() === '') {
+        throw new SdkMethodError('BAD_REQUEST', 'agents.sessions.answerQuestion requires a non-empty toolUseId');
+    }
+    if (typeof raw.answers !== 'object' || raw.answers === null || Array.isArray(raw.answers)) {
+        throw new SdkMethodError('BAD_REQUEST', 'agents.sessions.answerQuestion requires an answers object');
+    }
+    const answers = {};
+    for (const [key, value] of Object.entries(raw.answers)) {
+        if (typeof value !== 'string') {
+            throw new SdkMethodError('BAD_REQUEST', 'agents.sessions.answerQuestion answers values must all be strings');
+        }
+        answers[key] = value;
+    }
+    return { sessionId: raw.sessionId, toolUseId: raw.toolUseId, answers };
+}
+function parseAttachmentRefs(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw)) {
+        throw new SdkMethodError('BAD_REQUEST', 'agents.sessions.prompt attachments must be an array');
+    }
+    return raw.map((entry, index) => {
+        if (typeof entry !== 'object' || entry === null || typeof entry.path !== 'string' || entry.path === '') {
+            throw new SdkMethodError('BAD_REQUEST', `agents.sessions.prompt attachments[${index}] requires a non-empty string path`);
+        }
+        return { path: entry.path };
+    });
+}
+function parsePromptParams(params) {
+    const raw = paramsObject(params);
+    if (typeof raw.sessionId !== 'string' || raw.sessionId.trim() === '') {
+        throw new SdkMethodError('BAD_REQUEST', 'agents.sessions.prompt requires params { sessionId, prompt }');
+    }
+    if (typeof raw.prompt !== 'string' || raw.prompt.trim() === '') {
+        throw new SdkMethodError('BAD_REQUEST', 'agents.sessions.prompt requires a non-empty prompt');
+    }
+    return { sessionId: raw.sessionId, prompt: raw.prompt, attachments: parseAttachmentRefs(raw.attachments) };
+}
+function parseReplayParams(params) {
+    const raw = paramsObject(params);
+    if (typeof raw.sessionId !== 'string' || raw.sessionId.trim() === '') {
+        throw new SdkMethodError('BAD_REQUEST', 'agents.sessions.replay requires params { sessionId, afterSeq }');
+    }
+    if (typeof raw.afterSeq !== 'number' || !Number.isInteger(raw.afterSeq) || raw.afterSeq < 0) {
+        throw new SdkMethodError('BAD_REQUEST', 'agents.sessions.replay afterSeq must be a non-negative integer');
+    }
+    return { sessionId: raw.sessionId, afterSeq: raw.afterSeq };
+}
+function sessionNotFound(sessionId) {
+    return new SdkMethodError('BAD_REQUEST', `unknown sessionId '${sessionId}' — no session in this Space matches it`);
+}
+export function agentsSessionsListHandler(args) {
+    return requireHost().list(args.workingDir);
+}
+export function agentsSessionsCreateHandler(args) {
+    const { name } = parseCreateParams(args.params);
+    const grantScopes = args.grant ? [...args.grant.scopes] : [];
+    const summary = requireHost().create({ workingDir: args.workingDir, appId: args.appId, origin: args.origin, name, grantScopes });
+    logAppAudit({
+        appId: args.appId,
+        origin: args.origin,
+        method: 'agents.sessions.create',
+        decision: 'allow',
+        requestId: args.requestId,
+        spaceKey: args.spaceKey,
+        reason: `session ${summary.id} created${name ? ` (${name})` : ''}`,
+    });
+    return summary;
+}
+export function agentsSessionsAttachHandler(args) {
+    const sessionId = parseSessionIdParams(args.params, 'agents.sessions.attach');
+    const summary = requireHost().attach({ workingDir: args.workingDir, sessionId });
+    if (!summary)
+        throw sessionNotFound(sessionId);
+    return summary;
+}
+export function agentsSessionsCloseHandler(args) {
+    const sessionId = parseSessionIdParams(args.params, 'agents.sessions.close');
+    const closed = requireHost().close({ workingDir: args.workingDir, sessionId });
+    if (!closed)
+        throw sessionNotFound(sessionId);
+    logAppAudit({
+        appId: args.appId,
+        origin: args.origin,
+        method: 'agents.sessions.close',
+        decision: 'allow',
+        requestId: args.requestId,
+        spaceKey: args.spaceKey,
+        reason: `session ${sessionId} closed`,
+    });
+}
+export function agentsSessionsRenameHandler(args) {
+    const { sessionId, name } = parseRenameParams(args.params);
+    const summary = requireHost().rename({ workingDir: args.workingDir, sessionId, name });
+    if (!summary)
+        throw sessionNotFound(sessionId);
+    return summary;
+}
+export function agentsSessionsHistoryHandler(args) {
+    const sessionId = parseSessionIdParams(args.params, 'agents.sessions.history');
+    const result = requireHost().history({ workingDir: args.workingDir, sessionId });
+    if (!result)
+        throw sessionNotFound(sessionId);
+    return result;
+}
+export function agentsSessionsReplayHandler(args) {
+    const { sessionId, afterSeq } = parseReplayParams(args.params);
+    const outcome = requireHost().replay({ workingDir: args.workingDir, sessionId, afterSeq });
+    if (outcome.kind === 'not_found')
+        throw sessionNotFound(sessionId);
+    if (outcome.kind === 'gap') {
+        throw new SdkMethodError('STREAM_GAP', `session '${sessionId}' cannot be replayed from seq ${afterSeq}: events (${afterSeq + 1}..${outcome.evictedThroughSeq}) ` +
+            'have been evicted from the buffered window. Reconcile with agents.sessions.history.');
+    }
+    return outcome.result;
+}
+export function agentsSessionsApproveHandler(args) {
+    const { sessionId, approved } = parseApproveParams(args.params);
+    const ok = requireHost().approve({ workingDir: args.workingDir, sessionId, approved });
+    if (!ok)
+        throw sessionNotFound(sessionId);
+    logAppAudit({
+        appId: args.appId,
+        origin: args.origin,
+        method: 'agents.sessions.approve',
+        decision: 'allow',
+        requestId: args.requestId,
+        spaceKey: args.spaceKey,
+        reason: `session ${sessionId} ${approved ? 'approved' : 'rejected'} a pending tool-approval request`,
+    });
+    return null;
+}
+export function agentsSessionsAnswerQuestionHandler(args) {
+    const { sessionId, toolUseId, answers } = parseAnswerQuestionParams(args.params);
+    const ok = requireHost().answerQuestion({ workingDir: args.workingDir, sessionId, toolUseId, answers });
+    if (!ok)
+        throw sessionNotFound(sessionId);
+    logAppAudit({
+        appId: args.appId,
+        origin: args.origin,
+        method: 'agents.sessions.answerQuestion',
+        decision: 'allow',
+        requestId: args.requestId,
+        spaceKey: args.spaceKey,
+        reason: `session ${sessionId} answered question ${toolUseId}`,
+    });
+    return null;
+}
+export function agentsSessionsPromptHandler(args) {
+    const { sessionId, prompt, attachments: attachmentRefs } = parsePromptParams(args.params);
+    const attachments = attachmentRefs ? resolveAttachments(args, attachmentRefs) : undefined;
+    const result = requireHost().prompt({ workingDir: args.workingDir, sessionId, prompt, attachments });
+    if (!result)
+        throw sessionNotFound(sessionId);
+    logAppAudit({
+        appId: args.appId,
+        origin: args.origin,
+        method: 'agents.sessions.prompt',
+        decision: 'allow',
+        requestId: args.requestId,
+        spaceKey: args.spaceKey,
+        reason: `session ${sessionId} ${result.queued ? 'queued' : 'started'} a prompt`,
+    });
+    return result;
+}
+export function agentsSessionsStopHandler(args) {
+    const sessionId = parseSessionIdParams(args.params, 'agents.sessions.stop');
+    const ok = requireHost().stop({ workingDir: args.workingDir, sessionId });
+    if (!ok)
+        throw sessionNotFound(sessionId);
+    logAppAudit({
+        appId: args.appId,
+        origin: args.origin,
+        method: 'agents.sessions.stop',
+        decision: 'allow',
+        requestId: args.requestId,
+        spaceKey: args.spaceKey,
+        reason: `session ${sessionId} execution stopped`,
+    });
+    return null;
+}