maestro-lib (Library)

git clone https://github.com/RunMaestro/Maestro.git
cd Maestro
npm ci
npm run build:maestro-lib

{
	"dependencies": {
		"maestro-lib": "file:../Maestro/dist/maestro-lib"
	}
}

import { MAESTRO_LIB_VERSION } from 'maestro-lib';

const SUPPORTED = '0.2.';

if (!MAESTRO_LIB_VERSION.startsWith(SUPPORTED)) {
	throw new Error(`This tool needs maestro-lib ${SUPPORTED}x, found ${MAESTRO_LIB_VERSION}`);
}

import { BACKGROUND_STOP_GRACE_MS, planSessionTurn, runToCompletion } from 'maestro-lib';

export async function askOnce(cwd: string, prompt: string): Promise<string | undefined> {
	const planned = await planSessionTurn({ agentId: 'claude-code', cwd, prompt });
	if (!planned.ok) {
		throw new Error(`${planned.reason}: ${planned.error}`);
	}

	const turn = await runToCompletion(planned.spec, {
		agentId: 'claude-code',
		sessionId: 'my-tool',
		stopGraceMs: BACKGROUND_STOP_GRACE_MS,
	});
	return turn.answerText;
}

import { INTERACTIVE_STOP_GRACE_MS, planSessionTurn, runTurn, type ParsedEvent } from 'maestro-lib';

function show(event: ParsedEvent): void {
	switch (event.type) {
		case 'init':
			if (event.sessionId) console.log(`[session ${event.sessionId}]`);
			break;
		case 'text':
			if (!event.isReasoning && event.text) process.stdout.write(event.text);
			break;
		case 'tool_use':
			console.log(`\n[tool ${event.toolName ?? 'unknown'}]`);
			break;
		case 'usage':
			if (event.usage) console.log(`\n[${event.usage.outputTokens} tokens out]`);
			break;
		case 'error':
			console.error(`\n[error] ${event.text ?? ''}`);
			break;
		default:
			break;
	}
}

export async function streamTurn(cwd: string, prompt: string): Promise<void> {
	const planned = await planSessionTurn({ agentId: 'opencode', cwd, prompt });
	if (!planned.ok) throw new Error(planned.error);

	const { completed } = runTurn(
		planned.spec,
		{ agentId: 'opencode', sessionId: 'my-tool', stopGraceMs: INTERACTIVE_STOP_GRACE_MS },
		{
			onStarted: (pid) => console.log(`[started, pid ${pid ?? 'unknown'}]`),
			onEvent: (event) => show(event),
		}
	);
	await completed;
}

import {
	BACKGROUND_STOP_GRACE_MS,
	planSessionTurn,
	runToCompletion,
	type CompletedTurn,
} from 'maestro-lib';

async function send(cwd: string, prompt: string, resumeSessionId?: string): Promise<CompletedTurn> {
	const planned = await planSessionTurn({ agentId: 'claude-code', cwd, prompt, resumeSessionId });
	if (!planned.ok) throw new Error(planned.error);
	return runToCompletion(planned.spec, {
		agentId: 'claude-code',
		sessionId: 'my-tool',
		stopGraceMs: BACKGROUND_STOP_GRACE_MS,
	});
}

export async function conversation(cwd: string): Promise<void> {
	const first = await send(cwd, 'Name one prime number.');
	if (!first.sessionId) throw new Error('The provider did not report a session id');

	const second = await send(cwd, 'Now name the next one.', first.sessionId);
	console.log(second.answerText);
}

import {
	INTERACTIVE_STOP_GRACE_MS,
	planSessionTurn,
	runTurn,
	type CompletedTurn,
} from 'maestro-lib';

export async function runWithStop(
	cwd: string,
	prompt: string,
	timeoutMs: number
): Promise<CompletedTurn> {
	const planned = await planSessionTurn({ agentId: 'codex', cwd, prompt });
	if (!planned.ok) throw new Error(planned.error);

	const { handle, completed } = runTurn(planned.spec, {
		agentId: 'codex',
		sessionId: 'my-tool',
		stopGraceMs: INTERACTIVE_STOP_GRACE_MS,
	});

	// Ctrl+C stops the turn the way a user would; a second Ctrl+C ends it at once.
	const onSigint = (): void => {
		if (handle.stopRequested()) handle.terminateNow({ blocking: true });
		else handle.interrupt();
	};
	process.on('SIGINT', onSigint);

	// A turn that runs too long is terminated without the interrupt stage.
	const timer = setTimeout(() => handle.terminate(), timeoutMs);

	try {
		return await completed;
	} finally {
		clearTimeout(timer);
		process.off('SIGINT', onSigint);
	}
}

import type { CompletedTurn } from 'maestro-lib';

export function describeTurn(turn: CompletedTurn): string {
	switch (turn.outcome) {
		case 'completed':
			return turn.answerText ?? '(no answer)';
		case 'completed-with-warning':
			return `${turn.answerText ?? ''}\n(warning: the agent exited with code ${turn.exit.exitCode})`;
		case 'interrupted':
			return '(stopped)';
		case 'crashed': {
			if (turn.exit.spawnError) return `Could not start the agent: ${turn.exit.spawnError.message}`;
			if (turn.error) return `${turn.error.type}: ${turn.error.message}`;
			const how = turn.exit.signal ? `signal ${turn.exit.signal}` : `code ${turn.exit.exitCode}`;
			return `The agent exited with ${how}: ${turn.exit.stderrText.trim()}`;
		}
	}
}

import { setMaestroLibErrorReporter, setMaestroLibLogger } from 'maestro-lib';

const debug = process.env.MY_TOOL_DEBUG === '1';

setMaestroLibLogger({
	debug: (message, context) => {
		if (debug) console.error(`[debug] ${context ?? ''} ${message}`);
	},
	info: (message, context) => console.error(`[info] ${context ?? ''} ${message}`),
	warn: (message, context) => console.error(`[warn] ${context ?? ''} ${message}`),
	error: (message, context, data) =>
		console.error(`[error] ${context ?? ''} ${message}`, data ?? ''),
});

setMaestroLibErrorReporter({
	captureException: (error, extra) => console.error('[report]', error, extra ?? ''),
	captureMessage: (message, level, extra) =>
		console.error(`[report ${level ?? 'error'}]`, message, extra ?? ''),
});

import {
	BACKGROUND_STOP_GRACE_MS,
	createOutputParser,
	resolveTurnOutcome,
	startTurn,
	TurnCapture,
	type TurnOutcome,
	type TurnProcessSpec,
} from 'maestro-lib';

export async function runByHand(spec: TurnProcessSpec, agentId: string): Promise<TurnOutcome> {
	const parser = createOutputParser(agentId);
	if (!parser) throw new Error(`No parser for ${agentId}`);

	const capture = new TurnCapture(agentId, parser);
	const handle = startTurn(
		spec,
		{ onEvent: (event) => capture.handleEvent(event) },
		{ parser, stopGraceMs: BACKGROUND_STOP_GRACE_MS }
	);
	const exit = await handle.done;

	const { outcome } = resolveTurnOutcome(
		{
			exitCode: exit.exitCode,
			signal: exit.signal,
			interrupted: exit.interrupted,
			stderrText: exit.stderrText,
			stdoutText: exit.stdoutText,
			explicitError: capture.inBandError,
			stdinError: exit.stdinError,
			capturedAnswerText: capture.answerText,
			resultMessageSeen: capture.resultMessageSeen,
		},
		parser,
		{ providerId: agentId, sessionId: 'my-tool' }
	);
	return outcome;
}