astrocode-workflow 0.3.0 → 0.3.2

package/dist/src/config/schema.js

@@ -0,0 +1,223 @@
+import { z } from "zod";
+export const PermissionValueSchema = z.enum(["ask", "allow", "deny"]);
+const StageKeySchema = z.enum([
+    "frame",
+    "plan",
+    "spec",
+    "implement",
+    "review",
+    "verify",
+    "close",
+]);
+const InjectionModeSchema = z.enum(["visible", "silent"]);
+const TruncationPolicySchema = z
+    .object({
+    enabled: z.boolean().default(true),
+    truncate_all_tool_outputs: z.boolean().default(false),
+    max_chars_default: z.number().int().positive().default(200_000),
+    max_chars_webfetch: z.number().int().positive().default(40_000),
+    max_chars_diff: z.number().int().positive().default(120_000),
+    persist_truncated_outputs: z.boolean().default(true),
+})
+    .partial()
+    .default({});
+const ContextCompactionSchema = z
+    .object({
+    enabled: z.boolean().default(true),
+    snapshot_after_stage_count: z.number().int().positive().default(2),
+    snapshot_max_lines: z.number().int().positive().default(60),
+    baton_summary_max_lines: z.number().int().positive().default(25),
+    inject_max_chars: z.number().int().positive().default(18_000),
+})
+    .partial()
+    .default({});
+const ContinuationSchema = z
+    .object({
+    enabled: z.boolean().default(true),
+    injection_mode: InjectionModeSchema.default("visible"),
+    inject_on_session_idle: z.boolean().default(true),
+    session_idle_ms: z.number().int().positive().default(12_000),
+    inject_on_tool_done_if_run_active: z.boolean().default(true),
+    inject_on_message_done_if_run_active: z.boolean().default(true),
+    dedupe_window_ms: z.number().int().positive().default(20_000),
+    max_same_directive_repeats: z.number().int().positive().default(1),
+    auto_continue: z.boolean().default(false),
+    auto_continue_delay_ms: z.number().int().positive().default(1500),
+    max_auto_steps_per_session: z.number().int().positive().default(50),
+})
+    .partial()
+    .default({});
+const ToastsSchema = z
+    .object({
+    enabled: z.boolean().default(true),
+    throttle_ms: z.number().int().positive().default(1500),
+    show_run_started: z.boolean().default(true),
+    show_stage_started: z.boolean().default(true),
+    show_stage_completed: z.boolean().default(true),
+    show_stage_failed: z.boolean().default(true),
+    show_run_completed: z.boolean().default(true),
+    show_auto_continue: z.boolean().default(true),
+})
+    .partial()
+    .default({});
+const DbSchema = z
+    .object({
+    path: z.string().default(".astro/astro.db"),
+    busy_timeout_ms: z.number().int().positive().default(5000),
+    pragmas: z
+        .object({
+        journal_mode: z.enum(["WAL", "DELETE"]).default("WAL"),
+        synchronous: z.enum(["NORMAL", "FULL", "OFF"]).default("NORMAL"),
+        foreign_keys: z.boolean().default(true),
+        temp_store: z.enum(["DEFAULT", "MEMORY", "FILE"]).default("MEMORY"),
+    })
+        // Why: Zod's .default({}) requires the *type* to accept an empty object.
+        //       We still want runtime defaults for each key, so we make keys optional.
+        .partial()
+        .default({}),
+    schema_version_required: z.number().int().positive().default(2),
+    allow_auto_migrate: z.boolean().default(true),
+    fail_on_downgrade: z.boolean().default(true),
+})
+    // Why: allow "db: {}" (or missing db) while still applying defaults.
+    .partial()
+    .default({});
+const WorkflowSchema = z.object({
+    pipeline: z.array(StageKeySchema).default([
+        "frame",
+        "plan",
+        "spec",
+        "implement",
+        "review",
+        "verify",
+        "close",
+    ]),
+    genesis_planning: z.enum(["off", "first_story_only", "always"]).default("first_story_only"),
+    default_mode: z.enum(["step", "loop"]).default("step"),
+    default_max_steps: z.number().int().positive().default(1),
+    loop_max_steps_hard_cap: z.number().int().positive().default(200),
+    plan_max_tasks: z.number().int().positive().default(500),
+    plan_max_lines: z.number().int().positive().default(2000),
+    baton_summary_max_lines: z.number().int().positive().default(20),
+    forbid_prompt_narration: z.boolean().default(true),
+    single_active_run_per_repo: z.boolean().default(true),
+    lock_timeout_ms: z.number().int().positive().default(4000),
+    role_first_subagents: z.boolean().default(true),
+    evidence_required: z
+        .object({
+        verify: z.boolean().default(true),
+        implement: z.boolean().default(false),
+    })
+        // NOTE: We want callers to be able to omit the whole object ("{}")
+        // while still receiving per-field defaults at parse time.
+        .partial()
+        .default({}),
+}).partial().default({});
+const ArtifactsSchema = z.object({
+    root_dir: z.string().default(".astro"),
+    runs_dir: z.string().default(".astro/runs"),
+    spec_path: z.string().default(".astro/spec.md"),
+    write_full_baton_md: z.boolean().default(true),
+    write_baton_summary_md: z.boolean().default(true),
+    write_baton_output_json: z.boolean().default(true),
+    baton_filename: z.string().default("baton.md"),
+    baton_summary_filename: z.string().default("baton.summary.md"),
+    baton_json_filename: z.string().default("baton.json"),
+}).partial().default({});
+const AgentsSchema = z.object({
+    // Display name for the *primary* agent tab.
+    orchestrator_name: z.string().default("Astro"),
+    // Display names for the stage sub-agents.
+    stage_agent_names: z
+        .object({
+        frame: z.string().default("Frame"),
+        plan: z.string().default("Plan"),
+        spec: z.string().default("Spec"),
+        implement: z.string().default("Implement"),
+        review: z.string().default("Review"),
+        verify: z.string().default("Verify"),
+        close: z.string().default("Close"),
+    })
+        .partial()
+        .default({}),
+    librarian_name: z.string().default("Librarian"),
+    explore_name: z.string().default("Explore"),
+    qa_name: z.string().default("QA"),
+    agent_variant_overrides: z
+        .record(z.string(), z.object({
+        variant: z.string().optional(),
+        model: z.string().optional(),
+    }))
+        .default({}),
+}).partial().default({});
+const PermissionsSchema = z.object({
+    enforce_task_tool_restrictions: z.boolean().default(true),
+    deny_delegate_task_in_subagents: z.boolean().default(true),
+}).partial().default({});
+const GitSchema = z.object({
+    enabled: z.boolean().default(true),
+    allow_dirty_start: z.boolean().default(true),
+    auto_branch: z.boolean().default(true),
+    branch_prefix: z.string().default("astro/"),
+    auto_commit: z.boolean().default(false),
+    commit_message_template: z.string().default("astro: {{story_key}} {{title}}"),
+    persist_diff_artifacts: z.boolean().default(true),
+}).partial().default({});
+const InjectSchema = z
+    .object({
+    enabled: z.boolean().default(true),
+    scope_allowlist: z.array(z.string()).default(["repo", "global"]),
+    type_allowlist: z.array(z.string()).default(["note", "policy"]),
+    max_per_turn: z.number().int().positive().default(5),
+})
+    .partial()
+    .default({});
+const DebugSchema = z
+    .object({
+    telemetry: z
+        .object({
+        enabled: z.boolean().default(false),
+    })
+        .partial()
+        .default({}),
+})
+    .partial()
+    .default({});
+const UiSchema = z
+    .object({
+    toasts: ToastsSchema,
+    continue_prompt: z
+        .object({
+        enabled: z.boolean().default(true),
+        mode: z.enum(["toast_button", "popup", "chat_only"]).default("toast_button"),
+        idle_prompt_ms: z.number().int().positive().default(20_000),
+    })
+        .partial()
+        .default({}),
+})
+    .partial()
+    .default({});
+export const AstrocodeConfigSchema = z.object({
+    disabled_hooks: z.array(z.string()).default([]),
+    disabled_agents: z.array(z.string()).default([]),
+    disabled_commands: z.array(z.string()).default([]),
+    determinism: z
+        .object({
+        mode: z.enum(["on", "off"]).default("on"),
+        strict_stage_order: z.boolean().default(true),
+    })
+        .partial()
+        .default({}),
+    db: DbSchema,
+    workflow: WorkflowSchema,
+    continuation: ContinuationSchema,
+    truncation: TruncationPolicySchema,
+    context_compaction: ContextCompactionSchema,
+    artifacts: ArtifactsSchema,
+    agents: AgentsSchema,
+    permissions: PermissionsSchema,
+    git: GitSchema,
+    ui: UiSchema,
+    inject: InjectSchema,
+    debug: DebugSchema,
+}).partial().default({});

package/dist/src/hooks/continuation-enforcer.d.ts

@@ -0,0 +1,34 @@
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+type ToolExecuteAfterInput = {
+    tool: string;
+    sessionID?: string;
+};
+type ChatMessageInput = {
+    sessionID: string;
+    agent: string;
+};
+type EventInput = {
+    event: {
+        type: string;
+        properties: any;
+    };
+};
+type RuntimeState = {
+    db: SqliteDb | null;
+    limitedMode: boolean;
+    limitedModeReason: null | {
+        code: "db_init_failed" | "schema_too_old" | "schema_downgrade" | "schema_migration_failed";
+        details: any;
+    };
+};
+export declare function createContinuationEnforcer(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    runtime: RuntimeState;
+}): {
+    onToolAfter(input: ToolExecuteAfterInput): Promise<void>;
+    onChatMessage(_input: ChatMessageInput): Promise<void>;
+    onEvent(input: EventInput): Promise<void>;
+};
+export {};

package/dist/src/hooks/continuation-enforcer.js

@@ -0,0 +1,190 @@
+import { buildContextSnapshot } from "../workflow/context";
+import { decideNextAction, getActiveRun } from "../workflow/state-machine";
+import { buildContinueDirective } from "../workflow/directives";
+import { injectChatPrompt } from "../ui/inject";
+import { nowISO } from "../shared/time";
+import { createToastManager } from "../ui/toasts";
+function msFromIso(iso) {
+    const t = Date.parse(iso);
+    return Number.isFinite(t) ? t : 0;
+}
+export function createContinuationEnforcer(opts) {
+    const { ctx, config, runtime } = opts;
+    const { db } = runtime;
+    const toasts = createToastManager({ ctx, throttleMs: config.ui.toasts.throttle_ms });
+    const sessions = new Map();
+    function getState(sessionId) {
+        const cur = sessions.get(sessionId);
+        if (cur)
+            return cur;
+        const state = { lastHash: null, lastAtMs: 0, repeats: 0, autoSteps: 0, idleTimer: null, periodicTimer: null };
+        sessions.set(sessionId, state);
+        return state;
+    }
+    function clearIdleTimer(sessionId) {
+        const s = getState(sessionId);
+        if (s.idleTimer) {
+            clearTimeout(s.idleTimer);
+            s.idleTimer = null;
+        }
+    }
+    function clearPeriodicTimer(sessionId) {
+        const s = getState(sessionId);
+        if (s.periodicTimer) {
+            clearInterval(s.periodicTimer);
+            s.periodicTimer = null;
+        }
+    }
+    function scheduleIdleInjection(sessionId) {
+        clearIdleTimer(sessionId);
+        if (!config.continuation.enabled)
+            return;
+        if (!config.continuation.inject_on_session_idle)
+            return;
+        const delay = config.continuation.session_idle_ms;
+        const s = getState(sessionId);
+        s.idleTimer = setTimeout(() => {
+            // Fire and forget
+            void maybeInjectContinue(sessionId, "idle_timer");
+        }, delay);
+    }
+    function schedulePeriodicInjection(sessionId) {
+        clearPeriodicTimer(sessionId);
+        if (!config.continuation.enabled)
+            return;
+        // Inject every 3 minutes (180,000 ms)
+        const interval = 3 * 60 * 1000;
+        const s = getState(sessionId);
+        s.periodicTimer = setInterval(() => {
+            // Fire and forget
+            void maybeInjectContinue(sessionId, "periodic_timer");
+        }, interval);
+    }
+    function shouldDedupe(sessionId, directive) {
+        const s = getState(sessionId);
+        const now = Date.now();
+        // Memory window
+        if (s.lastHash === directive.hash && now - s.lastAtMs < config.continuation.dedupe_window_ms) {
+            if (s.repeats >= config.continuation.max_same_directive_repeats)
+                return true;
+        }
+        // DB window (durable)
+        const cutoff = new Date(now - config.continuation.dedupe_window_ms).toISOString();
+        const row = db
+            .prepare("SELECT COUNT(*) as c FROM continuations WHERE session_id=? AND directive_hash=? AND created_at > ?")
+            .get(sessionId, directive.hash, cutoff);
+        if ((row?.c ?? 0) >= config.continuation.max_same_directive_repeats)
+            return true;
+        return false;
+    }
+    async function recordContinuation(sessionId, runId, directive, reason) {
+        db.prepare("INSERT INTO continuations (session_id, run_id, directive_hash, kind, reason, created_at) VALUES (?, ?, ?, ?, ?, ?)").run(sessionId, runId, directive.hash, directive.kind, reason, nowISO());
+        const s = getState(sessionId);
+        const now = Date.now();
+        if (s.lastHash === directive.hash && now - s.lastAtMs < config.continuation.dedupe_window_ms) {
+            s.repeats += 1;
+        }
+        else {
+            s.lastHash = directive.hash;
+            s.repeats = 1;
+        }
+        s.lastAtMs = now;
+    }
+    function formatNextAction(next) {
+        switch (next.kind) {
+            case "idle":
+                return "No approved stories. Queue/approve a story.";
+            case "start_run":
+                return `Start run for story ${next.story_key}.`;
+            case "delegate_stage":
+                return `Delegate stage ${next.stage_key}.`;
+            case "await_stage_completion":
+                return `Await stage ${next.stage_key} completion. If you have stage output, call astro_stage_complete.`;
+            case "complete_run":
+                return `Complete run ${next.run_id}.`;
+            case "failed":
+                return `Run failed at stage ${next.stage_key}: ${next.error_text}`;
+            default:
+                return "Continue.";
+        }
+    }
+    async function maybeInjectContinue(sessionId, reason) {
+        if (!config.continuation.enabled)
+            return;
+        // Require active run
+        const active = getActiveRun(db);
+        if (!active)
+            return;
+        const next = decideNextAction(db, config);
+        // If failed, don't auto-inject "continue" — surface via toast and stop.
+        if (next.kind === "failed") {
+            if (config.ui.toasts.enabled && config.ui.toasts.show_stage_failed) {
+                await toasts.show({ title: "Astrocode", message: `Run failed at ${next.stage_key}`, variant: "error" });
+            }
+            return;
+        }
+        const nextActionStr = formatNextAction(next);
+        const context = buildContextSnapshot({ db, config, run_id: active.run_id, next_action: nextActionStr });
+        const directive = buildContinueDirective({
+            config,
+            run_id: active.run_id,
+            stage_key: active.current_stage_key,
+            next_action: nextActionStr,
+            context_snapshot_md: context,
+        });
+        if (shouldDedupe(sessionId, directive))
+            return;
+        await recordContinuation(sessionId, active.run_id, directive, reason);
+        // Injection mode
+        if (config.continuation.injection_mode === "visible") {
+            await injectChatPrompt({ ctx, sessionId, text: directive.body, agent: "Astro" });
+        }
+        else {
+            // Silent mode is TODO: requires experimental.chat.messages.transform.
+            // For v2-alpha, we fall back to visible injection but mark it.
+            await injectChatPrompt({ ctx, sessionId, text: directive.body + "\n\n(Injected in silent mode fallback)", agent: "Astro" });
+        }
+        if (config.ui.toasts.enabled && config.ui.toasts.show_auto_continue) {
+            await toasts.show({ title: "Astrocode", message: "Continue directive injected", variant: "info" });
+        }
+    }
+    // Public hook handlers
+    return {
+        async onToolAfter(input) {
+            const sessionId = input.sessionID ?? ctx.sessionID;
+            if (!sessionId)
+                return;
+            if (!config.continuation.inject_on_tool_done_if_run_active)
+                return;
+            // Inject continuation immediately after any tool execution
+            void maybeInjectContinue(sessionId, "tool_execution");
+            scheduleIdleInjection(sessionId);
+        },
+        async onChatMessage(_input) {
+            if (!config.continuation.inject_on_message_done_if_run_active)
+                return;
+            scheduleIdleInjection(_input.sessionID);
+        },
+        async onEvent(input) {
+            const type = input.event.type;
+            const sessionId = input.event.properties?.sessionID;
+            if (!sessionId)
+                return;
+            if (type === "session.idle") {
+                if (!config.continuation.inject_on_session_idle)
+                    return;
+                await maybeInjectContinue(sessionId, "session.idle");
+            }
+            if (type === "session.created") {
+                // When a session is created and there is an active run, nudge.
+                scheduleIdleInjection(sessionId);
+                schedulePeriodicInjection(sessionId);
+            }
+            if (type === "session.deleted") {
+                clearIdleTimer(sessionId);
+                clearPeriodicTimer(sessionId);
+                sessions.delete(sessionId);
+            }
+        },
+    };
+}

package/dist/src/hooks/inject-provider.d.ts

@@ -0,0 +1,22 @@
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+type ChatMessageInput = {
+    sessionID: string;
+    agent: string;
+};
+type RuntimeState = {
+    db: SqliteDb | null;
+    limitedMode: boolean;
+    limitedModeReason: null | {
+        code: "db_init_failed" | "schema_too_old" | "schema_downgrade" | "schema_migration_failed";
+        details: any;
+    };
+};
+export declare function createInjectProvider(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    runtime: RuntimeState;
+}): {
+    onChatMessage(input: ChatMessageInput): Promise<void>;
+};
+export {};

package/dist/src/hooks/inject-provider.js

@@ -0,0 +1,120 @@
+import { selectEligibleInjects } from "../tools/injects";
+import { injectChatPrompt } from "../ui/inject";
+import { nowISO } from "../shared/time";
+export function createInjectProvider(opts) {
+    const { ctx, config, runtime } = opts;
+    const { db } = runtime;
+    // Cache to avoid re-injecting the same injects repeatedly
+    const injectedCache = new Map();
+    function shouldSkipInject(injectId, nowMs) {
+        const lastInjected = injectedCache.get(injectId);
+        if (!lastInjected)
+            return false;
+        // Skip if injected within the last 5 minutes (configurable?)
+        const cooldownMs = 5 * 60 * 1000;
+        return nowMs - lastInjected < cooldownMs;
+    }
+    function markInjected(injectId, nowMs) {
+        injectedCache.set(injectId, nowMs);
+    }
+    function getInjectionDiagnostics(nowIso, scopeAllowlist, typeAllowlist) {
+        // Get ALL injects to analyze filtering
+        const allInjects = db.prepare("SELECT * FROM injects").all();
+        let total = allInjects.length;
+        let selected = 0;
+        let skippedExpired = 0;
+        let skippedScope = 0;
+        let skippedType = 0;
+        let eligibleIds = [];
+        for (const inject of allInjects) {
+            // Check expiration
+            if (inject.expires_at && inject.expires_at <= nowIso) {
+                skippedExpired++;
+                continue;
+            }
+            // Check scope
+            if (!scopeAllowlist.includes(inject.scope)) {
+                skippedScope++;
+                continue;
+            }
+            // Check type
+            if (!typeAllowlist.includes(inject.type)) {
+                skippedType++;
+                continue;
+            }
+            // This inject is eligible
+            selected++;
+            eligibleIds.push(inject.inject_id);
+        }
+        return {
+            now: nowIso,
+            scopes_considered: scopeAllowlist,
+            types_considered: typeAllowlist,
+            total_injects: total,
+            selected_eligible: selected,
+            skipped: {
+                expired: skippedExpired,
+                scope: skippedScope,
+                type: skippedType,
+            },
+            eligible_ids: eligibleIds,
+        };
+    }
+    async function injectEligibleInjects(sessionId) {
+        const now = nowISO();
+        const nowMs = Date.now();
+        // Get allowlists from config or defaults
+        const scopeAllowlist = config.inject?.scope_allowlist ?? ["repo", "global"];
+        const typeAllowlist = config.inject?.type_allowlist ?? ["note", "policy"];
+        const EMIT_TELEMETRY = config.debug?.telemetry?.enabled ?? false;
+        // Get diagnostic data
+        const diagnostics = getInjectionDiagnostics(now, scopeAllowlist, typeAllowlist);
+        const eligibleInjects = selectEligibleInjects(db, {
+            nowIso: now,
+            scopeAllowlist,
+            typeAllowlist,
+            limit: config.inject?.max_per_turn ?? 5,
+        });
+        let injected = 0;
+        let skippedDeduped = 0;
+        if (eligibleInjects.length === 0) {
+            // Log when no injects are eligible
+            if (EMIT_TELEMETRY) {
+                // eslint-disable-next-line no-console
+                console.log(`[Astrocode:inject] ${now} selected=${diagnostics.selected_eligible} injected=0 skipped={expired:${diagnostics.skipped.expired} scope:${diagnostics.skipped.scope} type:${diagnostics.skipped.type} deduped:0}`);
+            }
+            return;
+        }
+        // Inject each eligible inject, skipping recently injected ones
+        for (const inject of eligibleInjects) {
+            if (shouldSkipInject(inject.inject_id, nowMs)) {
+                skippedDeduped++;
+                continue;
+            }
+            // Format as injection message
+            const formattedText = `[Inject: ${inject.title}]\n\n${inject.body_md}`;
+            await injectChatPrompt({
+                ctx,
+                sessionId,
+                text: formattedText,
+                agent: "Astrocode"
+            });
+            injected++;
+            markInjected(inject.inject_id, nowMs);
+        }
+        // Log diagnostic summary
+        if (EMIT_TELEMETRY) {
+            // eslint-disable-next-line no-console
+            console.log(`[Astrocode:inject] ${now} selected=${diagnostics.selected_eligible} injected=${injected} skipped={expired:${diagnostics.skipped.expired} scope:${diagnostics.skipped.scope} type:${diagnostics.skipped.type} deduped:${skippedDeduped}}`);
+        }
+    }
+    // Public hook handlers
+    return {
+        async onChatMessage(input) {
+            if (!config.inject?.enabled)
+                return;
+            // Inject eligible injects before processing the user's message
+            await injectEligibleInjects(input.sessionID);
+        },
+    };
+}

package/dist/src/hooks/tool-output-truncator.d.ts

@@ -0,0 +1,25 @@
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+type ToolExecuteAfterInput = {
+    tool: string;
+    sessionID?: string;
+};
+type ToolExecuteAfterOutput = {
+    title?: string;
+    output?: string;
+    metadata?: Record<string, any>;
+};
+type RuntimeState = {
+    db: SqliteDb | null;
+    limitedMode: boolean;
+    limitedModeReason: null | {
+        code: "db_init_failed" | "schema_too_old" | "schema_downgrade" | "schema_migration_failed";
+        details: any;
+    };
+};
+export declare function createToolOutputTruncatorHook(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    runtime: RuntimeState;
+}): (input: ToolExecuteAfterInput, output: ToolExecuteAfterOutput) => Promise<void>;
+export {};

package/dist/src/hooks/tool-output-truncator.js

@@ -0,0 +1,57 @@
+import path from "node:path";
+import { getAstroPaths, ensureDir, toPosix } from "../shared/paths";
+import { nowISO } from "../shared/time";
+import { putArtifact } from "../workflow/artifacts";
+import { sha256Hex } from "../shared/hash";
+import { clampChars } from "../shared/text";
+import { getActiveRun } from "../workflow/state-machine";
+function pickMaxChars(toolName, cfg) {
+    if (toolName.includes("webfetch") || toolName.includes("web.run"))
+        return cfg.truncation.max_chars_webfetch;
+    if (toolName.includes("diff"))
+        return cfg.truncation.max_chars_diff;
+    return cfg.truncation.max_chars_default;
+}
+export function createToolOutputTruncatorHook(opts) {
+    const { ctx, config, runtime } = opts;
+    const { db } = runtime;
+    return async function toolExecuteAfter(input, output) {
+        if (!config.truncation.enabled)
+            return;
+        const toolName = input.tool;
+        const text = output.output ?? "";
+        const maxChars = pickMaxChars(toolName, config);
+        if (!text || text.length <= maxChars)
+            return;
+        const repoRoot = ctx.directory;
+        const paths = getAstroPaths(repoRoot, config.db.path);
+        ensureDir(paths.toolOutputDir);
+        const active = getActiveRun(db);
+        const timestamp = nowISO().replace(/[:.]/g, "-");
+        const relBase = active && config.truncation.persist_truncated_outputs
+            ? toPosix(path.join(".astro", "runs", active.run_id, "_tool_output"))
+            : toPosix(path.join(".astro", "tool_output"));
+        const relPath = toPosix(path.join(relBase, toolName.replace(/[^a-zA-Z0-9_-]/g, "_"), `${timestamp}.txt`));
+        const { artifact_id } = putArtifact({
+            repoRoot,
+            db,
+            run_id: active?.run_id ?? null,
+            stage_key: active?.current_stage_key ?? null,
+            type: "tool_output",
+            rel_path: relPath,
+            content: text,
+            meta: { tool: toolName, session_id: input.sessionID ?? null },
+        });
+        const digest = sha256Hex(text);
+        const head = clampChars(text, Math.min(maxChars, 4000));
+        output.output =
+            head +
+                `\n\n…(truncated; sha256=${digest})\n` +
+                `Full output saved: ${relPath}\n` +
+                `Artifact ID: ${artifact_id}`;
+        output.metadata = output.metadata ?? {};
+        output.metadata.truncated = true;
+        output.metadata.artifact_id = artifact_id;
+        output.metadata.full_output_path = relPath;
+    };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+declare const Astrocode: Plugin;
+export default Astrocode;