pi-gentic 0.1.0

package/dist/policy.js

@@ -0,0 +1,136 @@
+/**
+ * Policy and active-agent state.
+ *
+ * A session stores a tiny append-only recipe. This module resolves that recipe
+ * against current settings and current resources every time policy is needed.
+ */
+import { applyFilterList, coalesce, isRecord, mergeFilterLayers } from "./core.js";
+const DEFAULT_ACCESS = ["*"];
+/** Combines defaults, the active agent, and runtime overrides into usable policy. */
+export function resolveSessionPolicy({ settings, activeAgent, overrides, allAgents, allTools, allSkills, }) {
+    const defaults = settings.agentDefaults ?? {};
+    const agentless = settings.agentlessSession ?? {};
+    const base = activeAgent ? defaults : agentless;
+    const merged = mergeObjects(base, activeAgent ?? {});
+    const resolved = mergeObjects(merged, overrides ?? {});
+    const agentsFilter = (activeAgent
+        ? mergeFilterLayers(defaults.agents, activeAgent.agents, overrides?.agents)
+        : mergeFilterLayers(agentless.agents, overrides?.agents)) ??
+        DEFAULT_ACCESS;
+    const toolsFilter = (activeAgent
+        ? mergeFilterLayers(defaults.tools, activeAgent.tools, overrides?.tools)
+        : mergeFilterLayers(agentless.tools, overrides?.tools)) ?? DEFAULT_ACCESS;
+    const skillsFilter = (activeAgent
+        ? mergeFilterLayers(defaults.skills, activeAgent.skills, overrides?.skills)
+        : mergeFilterLayers(agentless.skills, overrides?.skills)) ??
+        DEFAULT_ACCESS;
+    const systemPromptFilesFilter = activeAgent
+        ? mergeFilterLayers(defaults.systemPromptFiles, activeAgent.systemPromptFiles, overrides?.systemPromptFiles)
+        : mergeFilterLayers(agentless.systemPromptFiles, overrides?.systemPromptFiles);
+    return {
+        agentName: activeAgent?.name,
+        description: resolved.description,
+        instructions: resolved.instructions,
+        model: resolved.model,
+        thinking: resolved.thinking,
+        theme: resolved.theme,
+        maxSubagentDepth: coalesce(resolved.maxSubagentDepth, activeAgent ? 2 : settings.globalMaxSubagentDepth),
+        agentsTool: mergeObjects(defaults.agentsTool ?? {}, mergeObjects(activeAgent?.agentsTool ?? {}, overrides?.agentsTool ?? {})),
+        systemPromptFiles: systemPromptFilesFilter,
+        resources: {
+            agents: applyFilterList(allAgents, agentsFilter),
+            tools: applyFilterList(allTools, toolsFilter),
+            skills: applyFilterList(allSkills, skillsFilter),
+        },
+        recipe: {
+            agentReference: activeAgent?.name,
+            overrides: overrides ?? undefined,
+        },
+    };
+}
+/** Reads the latest pi-gentic state entry from append-only session history. */
+export function getActiveState(sessionManager) {
+    const entries = sessionManager.getEntries?.() ?? [];
+    for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index];
+        if (entry.type === "custom" && entry.customType === "pi-gentic:state") {
+            return sanitizeState(entry.data);
+        }
+    }
+    return { agentName: undefined, overrides: undefined };
+}
+/** Writes a new durable active-agent recipe without mutating older entries. */
+export function appendActiveState(sessionManager, state) {
+    sessionManager.appendCustomEntry("pi-gentic:state", sanitizeState(state));
+}
+function sanitizeState(value) {
+    if (!value || typeof value !== "object")
+        return { agentName: undefined, overrides: undefined };
+    return {
+        agentName: typeof value.agentName === "string" && value.agentName
+            ? value.agentName
+            : undefined,
+        overrides: value.overrides && typeof value.overrides === "object"
+            ? value.overrides
+            : undefined,
+    };
+}
+function mergeObjects(base, patch) {
+    const result = { ...(base ?? {}) };
+    for (const [key, value] of Object.entries(patch ?? {})) {
+        result[key] =
+            isPlainObject(value) && isPlainObject(result[key])
+                ? mergeObjects(result[key], value)
+                : value;
+    }
+    return result;
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export const AGENT_CYCLE_SHORTCUT = "f7";
+export function nextAgentName(currentAgentName, agents) {
+    const cycle = [undefined, ...agents.map((agent) => agent.name)];
+    const index = cycle.findIndex((name) => name === currentAgentName);
+    return cycle[index === -1 ? 1 : (index + 1) % cycle.length];
+}
+export function hasPersistedAgentState(sessionManager) {
+    return (sessionManager.getEntries?.() ?? []).some((entry) => entry.type === "custom" && entry.customType === "pi-gentic:state");
+}
+export function shouldApplyDefaultAgent(event, sessionManager) {
+    return (["new", "startup"].includes(event?.reason) &&
+        isBlankSession(sessionManager) &&
+        !hasPersistedAgentState(sessionManager));
+}
+function isBlankSession(sessionManager) {
+    const context = sessionManager.buildSessionContext?.();
+    if (context)
+        return (context.messages ?? []).length === 0;
+    return !(sessionManager.getEntries?.() ?? []).some((entry) => entry.type === "message" || entry.type === "custom_message");
+}
+export function configuredDefaultAgent(settings) {
+    return typeof settings?.defaultAgent === "string" &&
+        settings.defaultAgent.trim()
+        ? settings.defaultAgent.trim()
+        : undefined;
+}
+export function activeAgentName(sessionManager) {
+    return getActiveState(sessionManager).agentName;
+}
+export function filterAvailableAgents(config, policy) {
+    const resources = policy.resources;
+    const allowedAgents = Array.isArray(resources?.agents)
+        ? resources.agents.map(String)
+        : [];
+    const allowed = new Set(allowedAgents);
+    const agents = Array.isArray(config.agents)
+        ? config.agents.filter(isRecord)
+        : [];
+    return agents.filter((agent) => allowed.has(String(agent.name)));
+}
+export function assertAvailableAgent(agentName, agents) {
+    const agent = agents.find((item) => String(item.name).toLowerCase() === String(agentName ?? "").toLowerCase());
+    if (!agent)
+        throw new Error(`Unavailable agent "${agentName}". Available agents: ${agents.map((item) => item.name).join(", ") || "none"}.`);
+    return agent;
+}

package/dist/prompt.d.ts

@@ -0,0 +1,12 @@
+/** Produces the final prompt Pi will use before an agent run starts. */
+export declare function buildResolvedSystemPrompt({ baseSystemPrompt, config, policy, skillEntries, }: {
+    baseSystemPrompt: any;
+    config: any;
+    policy: any;
+    skillEntries: any;
+}): string;
+export declare function mergeSkillEntries(primary?: AnyRecord[], secondary?: AnyRecord[]): any[];
+export declare function availableAgentLines(agents: any, allowedNames: any): any;
+/** Extracts native Pi skill metadata so policy can filter it before display. */
+export declare function parseSkillEntries(systemPrompt: any): AnyRecord[];
+export declare function filterSkillPrompt(systemPrompt: any, skillEntries: any, allowedSkills: any): string;

package/dist/prompt.js

@@ -0,0 +1,226 @@
+/**
+ * Prompt construction for Pi sessions.
+ *
+ * Policy decides which agents, skills, and prompt files are visible. This file
+ * turns that resolved policy into human-readable system prompt text.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { applyFilterList, isRecord } from "./core.js";
+const AGENT_SYSTEM_PROMPT = "@agent/SYSTEM.md";
+const DELEGATION_PROMPT = "@agent/extensions/pi-gentic/DELEGATION.md";
+/** Produces the final prompt Pi will use before an agent run starts. */
+export function buildResolvedSystemPrompt({ baseSystemPrompt, config, policy, skillEntries, }) {
+    const resolvedSkillEntries = mergeSkillEntries(skillEntries, parseSkillEntries(baseSystemPrompt));
+    const sources = promptSources({ baseSystemPrompt, config, policy });
+    const sections = [
+        ...sources
+            .filter((source) => source.slot === "native")
+            .map((source) => source.content),
+        policy.instructions,
+        ...sources
+            .filter((source) => source.slot !== "native")
+            .map((source) => source.content),
+        agentsSection(config, policy),
+        namingSection(policy),
+        skillsSection(resolvedSkillEntries, policy),
+    ]
+        .map(cleanSection)
+        .filter(Boolean);
+    return sections.join("\n\n");
+}
+export function mergeSkillEntries(primary = [], secondary = []) {
+    const merged = new Map();
+    for (const entry of [...primary, ...secondary]) {
+        if (!entry?.name || merged.has(entry.name))
+            continue;
+        merged.set(entry.name, entry);
+    }
+    return [...merged.values()];
+}
+export function availableAgentLines(agents, allowedNames) {
+    const allowed = new Set(allowedNames);
+    const lines = agents
+        .filter((agent) => allowed.has(agent.name))
+        .map((agent) => `- ${agent.name}: ${agent.description ?? ""}`.trim());
+    return lines.join("\n") || "none";
+}
+/** Extracts native Pi skill metadata so policy can filter it before display. */
+export function parseSkillEntries(systemPrompt) {
+    const entries = [];
+    const block = String(systemPrompt ?? "").match(/<available_skills>[\s\S]*?<\/available_skills>/)?.[0];
+    if (!block)
+        return entries;
+    for (const match of block.matchAll(/<skill>[\s\S]*?<\/skill>/g)) {
+        const skillBlock = match[0];
+        const name = xmlValue(skillBlock, "name");
+        if (name)
+            entries.push({
+                name,
+                description: xmlValue(skillBlock, "description") ?? "",
+                location: xmlValue(skillBlock, "location") ?? "",
+                block: skillBlock,
+            });
+    }
+    return entries;
+}
+export function filterSkillPrompt(systemPrompt, skillEntries, allowedSkills) {
+    const prompt = removeNativeSkillSection(systemPrompt);
+    const skills = readableSkillLines(skillEntries, allowedSkills);
+    return skills.length
+        ? [prompt.trim(), "Available skills", ...skills].filter(Boolean).join("\n")
+        : prompt;
+}
+function promptSources({ baseSystemPrompt, config, policy }) {
+    const filters = Array.isArray(policy.systemPromptFiles)
+        ? policy.systemPromptFiles
+        : undefined;
+    const sources = [
+        ...nativePromptSources(baseSystemPrompt),
+        ...delegationSources(config, policy),
+        ...promptFileSources(config, filters),
+    ].filter((source) => source.content);
+    if (!filters)
+        return sources;
+    const allowed = new Set(applyFilterList(sources.map((source) => source.id), filters));
+    return sources.filter((source) => allowed.has(source.id));
+}
+function nativePromptSources(systemPrompt) {
+    const prompt = removeNativeSkillSection(systemPrompt);
+    const projectSources = [];
+    const withoutProjectInstructions = prompt.replace(/<project_instructions\b([^>]*)>([\s\S]*?)<\/project_instructions>/g, (full, attributes, body) => {
+        const sourcePath = attributes.match(/\bpath=["']([^"']+)["']/)?.[1] ?? "AGENTS.md";
+        projectSources.push({
+            id: sourcePath,
+            content: stripXmlTags(body).trim(),
+        });
+        return "";
+    });
+    return [
+        {
+            id: AGENT_SYSTEM_PROMPT,
+            slot: "native",
+            content: stripXmlTags(withoutProjectInstructions).trim(),
+        },
+        ...projectSources.map((source) => ({ ...source, slot: "native" })),
+    ];
+}
+function delegationSources(config, policy) {
+    if (!canUseAgentsTool(policy) ||
+        (policy.resources?.agents ?? []).length === 0)
+        return [];
+    return (config.roots ?? [])
+        .map((root) => {
+        const filePath = path.join(root, "DELEGATION.md");
+        return existsSync(filePath)
+            ? {
+                id: DELEGATION_PROMPT,
+                slot: "delegation",
+                content: readFileSync(filePath, "utf8").trim(),
+            }
+            : undefined;
+    })
+        .filter(Boolean);
+}
+function promptFileSources(config, filters) {
+    return promptFileRefs(filters)
+        .map((filePath) => ({
+        id: filePath,
+        slot: "file",
+        content: readPromptFile(filePath, config),
+    }))
+        .filter((source) => source.content);
+}
+function promptFileRefs(filters) {
+    if (!Array.isArray(filters))
+        return [];
+    return filters
+        .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+        .filter(Boolean)
+        .flatMap((entry) => entry.startsWith("+")
+        ? [entry.slice(1)]
+        : entry.startsWith("!") || entry.startsWith("-") || entry === "*"
+            ? []
+            : [entry])
+        .filter((entry) => entry && !entry.includes("*") && !entry.includes("?"));
+}
+function agentsSection(config, policy) {
+    if (!canUseAgentsTool(policy))
+        return "";
+    const lines = availableAgentLines(config.agents ?? [], policy.resources?.agents ?? []);
+    return lines === "none" ? "" : `Available agents\n${lines}`;
+}
+function namingSection(policy) {
+    return canUseAgentsTool(policy)
+        ? "When generating a session or worktree name, it must be 3 words long max."
+        : "";
+}
+function skillsSection(skillEntries, policy) {
+    const lines = readableSkillLines(skillEntries, policy.resources?.skills ?? []);
+    return lines.length ? ["Available skills", ...lines].join("\n") : "";
+}
+function readableSkillLines(skillEntries, allowedSkills) {
+    const allowed = new Set(allowedSkills);
+    return skillEntries
+        .filter((skill) => allowed.has(skill.name))
+        .map((skill) => [
+        `- ${skill.name}: ${skill.description}`.trim(),
+        skill.location ? `  Path: ${skill.location}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n"));
+}
+function canUseAgentsTool(policy) {
+    return ((policy.resources?.tools ?? []).includes("agents") &&
+        (policy.resources?.agents ?? []).length > 0);
+}
+function readPromptFile(filePath, config) {
+    const resolved = resolvePromptFile(filePath, config);
+    if (!resolved)
+        return "";
+    try {
+        return readFileSync(resolved, "utf8").trim();
+    }
+    catch {
+        return "";
+    }
+}
+function resolvePromptFile(filePath, config) {
+    if (!filePath || typeof filePath !== "string")
+        return undefined;
+    const candidates = [];
+    if (path.isAbsolute(filePath))
+        candidates.push(filePath);
+    const roots = Array.isArray(config.roots) ? config.roots : [];
+    for (const root of roots) {
+        if (typeof root === "string")
+            candidates.push(path.resolve(root, filePath));
+    }
+    const activeAgent = config.activeAgent;
+    const sourcePath = isRecord(activeAgent) && typeof activeAgent.sourcePath === "string"
+        ? activeAgent.sourcePath
+        : undefined;
+    if (sourcePath && !path.isAbsolute(filePath))
+        candidates.push(path.resolve(path.dirname(sourcePath.split("#")[0]), filePath));
+    candidates.push(path.resolve(filePath));
+    return candidates.find((candidate) => existsSync(candidate));
+}
+function removeNativeSkillSection(systemPrompt) {
+    return String(systemPrompt ?? "")
+        .replace(/\n*The following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>/, "")
+        .trim();
+}
+function stripXmlTags(text) {
+    return String(text ?? "")
+        .replace(/<\/?(?:project_context|project_instructions|active-agent|available_skills|skill|name|description|location)(?:\s+[^>]*)?>/g, "")
+        .replace(/^[ \t]+$/gm, "")
+        .replace(/\n{3,}/g, "\n\n");
+}
+function cleanSection(value) {
+    return stripXmlTags(value).trim();
+}
+function xmlValue(block, tag) {
+    return block
+        .match(new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`))?.[1]
+        ?.trim();
+}

package/dist/runs.d.ts

@@ -0,0 +1,99 @@
+export declare function abortActor(ctx: any): string;
+export declare function shouldDeferSendCompletion({ async, awaitCompletion, }?: AnyRecord): boolean;
+export declare function sendPendingText({ async, agentName, sessionId, message, details, }: {
+    async: any;
+    agentName: any;
+    sessionId: any;
+    message: any;
+    details: any;
+}): string;
+export declare function sendConfirmationText(agentName: unknown, sessionId: unknown, message: string, options?: AnyRecord): string;
+export declare function sendStatusText(details?: AnyRecord): string;
+export declare function deliverSendContextToCaller({ pi, ctx, target, message, async, fork, }: {
+    pi: any;
+    ctx: any;
+    target: any;
+    message: any;
+    async: any;
+    fork: any;
+}): void;
+/** Delivers the target answer to the live caller, or persists it for later. */
+export declare function deliverReturnToCaller({ pi, ctx, callerSessionId, callerSessionManager, text, invoke, persist, invokeInactiveCaller, visibleSession, }: {
+    pi: any;
+    ctx: any;
+    callerSessionId: any;
+    callerSessionManager: any;
+    text: any;
+    invoke: any;
+    persist: any;
+    invokeInactiveCaller: any;
+    visibleSession: any;
+}): Promise<string>;
+export declare function deliverToLiveCaller({ pi, ctx, callerSessionId, text, invoke, visibleSession, }: {
+    pi: any;
+    ctx: any;
+    callerSessionId: any;
+    text: any;
+    invoke: any;
+    visibleSession: any;
+}): Promise<{
+    delivered: boolean;
+    mode?: undefined;
+} | {
+    delivered: boolean;
+    mode: string;
+}>;
+export declare function persistReturnForCaller({ callerSessionManager, text, invoke, persist, }: {
+    callerSessionManager: any;
+    text: any;
+    invoke: any;
+    persist: any;
+}): void;
+export declare function sendUserMessageOptions(ctx: any): {
+    deliverAs: string;
+};
+export declare function persistSynchronousToolCard(ctx: PiContext, input: AnyRecord, result: AnyRecord, persist?: (sessionManager: PiSessionManager) => void): void;
+export declare function displayTargetAnswerIfVisible({ ctx, target, targetSessionId, text, }: {
+    ctx: any;
+    target: any;
+    targetSessionId: any;
+    text: any;
+}): Promise<boolean>;
+export declare function contextStillActive(ctx: any, callerSessionId?: string): boolean;
+/** Tracks assistant and tool activity so cards can update while a run is live. */
+export declare function createSessionActivityMonitor(baseDetails: any, publish: any): {
+    readonly activities: any;
+    observe(event: any): void;
+    finish({ activities }: {
+        activities: any;
+    }): any;
+    stop(status: string, updates?: AnyRecord): any;
+    fail(error: any): any;
+};
+export declare function collectSessionActivities(session: any): any;
+export declare function mergeActivities(...activityLists: unknown[][]): AnyRecord[];
+export declare function lastRuntimeActivities(runtime: any): any;
+export declare function latestActivityLines(runtime: any, count?: number): any;
+export declare function formatActivityLine(activity: any): string;
+/** Converts the target session transcript into the result returned to the caller. */
+export declare function sessionRunOutcome(runtime: AnyRecord, { request, error }?: AnyRecord): {
+    status: string;
+    text: string;
+};
+export declare function sessionOutcomeText(runtime: AnyRecord, kind: string, { request, error }?: AnyRecord): string;
+/** Summarizes one runtime for status cards and tool responses. */
+export declare function sessionStatus(runtime: any): {
+    text: string;
+    sessionId: any;
+    agentName: any;
+    running: boolean;
+    state: string;
+    pendingMessages: number;
+    pendingText: string;
+    inactiveMs: number;
+    inactiveText: string;
+    runningMs: number;
+    runningText: string;
+    lastActivities: any;
+};
+export declare function formatSessionStatus(status: any): string;