@zelari/core 0.7.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 N-THEM Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/agents/advancedTools.d.ts

@@ -0,0 +1,7 @@
+import type { EnhancedToolDefinition } from '../types/systemTypes.js';
+/**
+ * Advanced tools: RAG search, mind-map node creation, milestones, task updates
+ * and idea clustering.
+ */
+export declare const ADVANCED_TOOL_DEFINITIONS: EnhancedToolDefinition[];
+//# sourceMappingURL=advancedTools.d.ts.map

package/dist/agents/advancedTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advancedTools.d.ts","sourceRoot":"","sources":["../../src/agents/advancedTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAiB,MAAM,yBAAyB,CAAC;AAcrF;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,sBAAsB,EAgG7D,CAAC"}

package/dist/agents/advancedTools.js

@@ -0,0 +1,115 @@
+/** Helper to build a ToolParameter concisely. */
+function p(name, type, description, required, extra) {
+    return { name, type, description, required, ...extra };
+}
+/**
+ * Advanced tools: RAG search, mind-map node creation, milestones, task updates
+ * and idea clustering.
+ */
+export const ADVANCED_TOOL_DEFINITIONS = [
+    {
+        name: 'searchRAG',
+        description: 'Query the hybrid RAG knowledge base and return the most relevant chunks.',
+        category: 'analysis',
+        parameters: [
+            p('query', 'string', 'Natural-language query', true),
+            p('topK', 'number', 'Number of results to return', false, { default: 6 }),
+        ],
+        execute: (args, ctx) => {
+            if (!ctx.ragQuery)
+                return 'RAG search not available in this context.';
+            const query = args['query'] ?? '';
+            const topK = args['topK'] ?? 6;
+            const results = ctx.ragQuery(query, topK);
+            if (results.length === 0)
+                return 'No relevant knowledge found in RAG index.';
+            return results
+                .map((r, i) => `${i + 1}. ${r.title} (score: ${r.score.toFixed(2)})\n   ${r.content.slice(0, 160)}`)
+                .join('\n');
+        },
+    },
+    {
+        name: 'createMindMapNode',
+        description: 'Add a single node to the current mind map.',
+        category: 'mindmap',
+        parameters: [
+            p('label', 'string', 'Node label', true),
+            p('content', 'string', 'Short node content/description', false),
+        ],
+        execute: (args, ctx) => {
+            if (!ctx.createMindMapNode)
+                return 'Mind map not available in this context.';
+            ctx.createMindMapNode({
+                label: args['label'] ?? 'Node',
+                content: args['content'] ?? '',
+            });
+            return `Mind map node "${args['label']}" added.`;
+        },
+    },
+    {
+        name: 'createMilestone',
+        description: 'Create a milestone in the active project.',
+        category: 'project',
+        parameters: [
+            p('title', 'string', 'Milestone title', true),
+            p('description', 'string', 'Milestone description', false),
+            p('dueDate', 'string', 'Due date (ISO string)', false),
+        ],
+        execute: (args, ctx) => {
+            if (!ctx.createMilestone)
+                return 'Project milestones not available in this context.';
+            ctx.createMilestone({
+                title: args['title'] ?? 'Milestone',
+                description: args['description'] ?? '',
+                dueDate: args['dueDate'],
+            });
+            ctx.addActivity('project', 'milestone created', args['title'] ?? 'Milestone');
+            return `Milestone "${args['title']}" created.`;
+        },
+    },
+    {
+        name: 'updateTask',
+        description: 'Update an existing task (status, priority, description).',
+        category: 'project',
+        parameters: [
+            p('taskId', 'string', 'Task id to update', true),
+            p('status', 'string', 'New status', false, { enum: ['todo', 'in-progress', 'done', 'blocked'] }),
+            p('priority', 'string', 'New priority', false, { enum: ['low', 'medium', 'high', 'critical'] }),
+            p('description', 'string', 'New description', false),
+        ],
+        execute: (args, ctx) => {
+            if (!ctx.updateTask)
+                return 'Task updates not available in this context.';
+            const taskId = args['taskId'] ?? '';
+            const updates = {};
+            if (args['status'] !== undefined)
+                updates.status = args['status'];
+            if (args['priority'] !== undefined)
+                updates.priority = args['priority'];
+            if (args['description'] !== undefined)
+                updates.description = args['description'];
+            ctx.updateTask(taskId, updates);
+            return `Task ${taskId} updated.`;
+        },
+    },
+    {
+        name: 'clusterIdeas',
+        description: 'Group ideas by similarity into a named cluster.',
+        category: 'ideas',
+        parameters: [
+            p('ideaIds', 'string[]', 'Idea ids to cluster', true),
+            p('clusterName', 'string', 'Name for the new cluster', true),
+            p('color', 'string', 'Cluster color (hex)', false, { default: '#3b82f6' }),
+        ],
+        execute: (args, ctx) => {
+            if (!ctx.clusterIdeas)
+                return 'Idea clustering not available in this context.';
+            const ideaIds = args['ideaIds'] ?? [];
+            const clusterName = args['clusterName'] ?? 'Cluster';
+            const color = args['color'] ?? '#3b82f6';
+            ctx.clusterIdeas(ideaIds, clusterName, color);
+            return `Clustered ${ideaIds.length} ideas into "${clusterName}".`;
+        },
+    },
+];
+//# sourceMappingURL=advancedTools.js.map

package/dist/agents/advancedTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advancedTools.js","sourceRoot":"","sources":["../../src/agents/advancedTools.ts"],"names":[],"mappings":"AAGA,iDAAiD;AACjD,SAAS,CAAC,CACR,IAAY,EACZ,IAA2B,EAC3B,WAAmB,EACnB,QAAiB,EACjB,KAA8B;IAE9B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAA6B;IACjE;QACE,IAAI,EAAE,WAAW;QACjB,WAAW,EAAE,0EAA0E;QACvF,QAAQ,EAAE,UAAU;QACpB,UAAU,EAAE;YACV,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,wBAAwB,EAAE,IAAI,CAAC;YACpD,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,6BAA6B,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;SAC1E;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;YACrB,IAAI,CAAC,GAAG,CAAC,QAAQ;gBAAE,OAAO,2CAA2C,CAAC;YACtE,MAAM,KAAK,GAAI,IAAI,CAAC,OAAO,CAAY,IAAI,EAAE,CAAC;YAC9C,MAAM,IAAI,GAAI,IAAI,CAAC,MAAM,CAAY,IAAI,CAAC,CAAC;YAC3C,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC1C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,2CAA2C,CAAC;YAC7E,OAAO,OAAO;iBACX,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,KAAK,YAAY,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;iBACnG,IAAI,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC;KACF;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,4CAA4C;QACzD,QAAQ,EAAE,SAAS;QACnB,UAAU,EAAE;YACV,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,CAAC;YACxC,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,gCAAgC,EAAE,KAAK,CAAC;SAChE;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;YACrB,IAAI,CAAC,GAAG,CAAC,iBAAiB;gBAAE,OAAO,yCAAyC,CAAC;YAC7E,GAAG,CAAC,iBAAiB,CAAC;gBACpB,KAAK,EAAG,IAAI,CAAC,OAAO,CAAY,IAAI,MAAM;gBAC1C,OAAO,EAAG,IAAI,CAAC,SAAS,CAAY,IAAI,EAAE;aAC3C,CAAC,CAAC;YACH,OAAO,kBAAkB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;QACnD,CAAC;KACF;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,2CAA2C;QACxD,QAAQ,EAAE,SAAS;QACnB,UAAU,EAAE;YACV,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,IAAI,CAAC;YAC7C,CAAC,CAAC,aAAa,EAAE,QAAQ,EAAE,uBAAuB,EAAE,KAAK,CAAC;YAC1D,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,uBAAuB,EAAE,KAAK,CAAC;SACvD;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;YACrB,IAAI,CAAC,GAAG,CAAC,eAAe;gBAAE,OAAO,mDAAmD,CAAC;YACrF,GAAG,CAAC,eAAe,CAAC;gBAClB,KAAK,EAAG,IAAI,CAAC,OAAO,CAAY,IAAI,WAAW;gBAC/C,WAAW,EAAG,IAAI,CAAC,aAAa,CAAY,IAAI,EAAE;gBAClD,OAAO,EAAE,IAAI,CAAC,SAAS,CAAuB;aAC/C,CAAC,CAAC;YACH,GAAG,CAAC,WAAW,CAAC,SAAS,EAAE,mBAAmB,EAAG,IAAI,CAAC,OAAO,CAAY,IAAI,WAAW,CAAC,CAAC;YAC1F,OAAO,cAAc,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC;QACjD,CAAC;KACF;IACD;QACE,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,0DAA0D;QACvE,QAAQ,EAAE,SAAS;QACnB,UAAU,EAAE;YACV,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,mBAAmB,EAAE,IAAI,CAAC;YAChD,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC;YAChG,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC;YAC/F,CAAC,CAAC,aAAa,EAAE,QAAQ,EAAE,iBAAiB,EAAE,KAAK,CAAC;SACrD;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;YACrB,IAAI,CAAC,GAAG,CAAC,UAAU;gBAAE,OAAO,6CAA6C,CAAC;YAC1E,MAAM,MAAM,GAAI,IAAI,CAAC,QAAQ,CAAY,IAAI,EAAE,CAAC;YAChD,MAAM,OAAO,GAA4B,EAAE,CAAC;YAC5C,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,SAAS;gBAAE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;YAClE,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,SAAS;gBAAE,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;YACxE,IAAI,IAAI,CAAC,aAAa,CAAC,KAAK,SAAS;gBAAE,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;YACjF,GAAG,CAAC,UAAU,CAAC,MAAM,EAAE,OAAwB,CAAC,CAAC;YACjD,OAAO,QAAQ,MAAM,WAAW,CAAC;QACnC,CAAC;KACF;IACD;QACE,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,iDAAiD;QAC9D,QAAQ,EAAE,OAAO;QACjB,UAAU,EAAE;YACV,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,qBAAqB,EAAE,IAAI,CAAC;YACrD,CAAC,CAAC,aAAa,EAAE,QAAQ,EAAE,0BAA0B,EAAE,IAAI,CAAC;YAC5D,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,qBAAqB,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;SAC3E;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;YACrB,IAAI,CAAC,GAAG,CAAC,YAAY;gBAAE,OAAO,gDAAgD,CAAC;YAC/E,MAAM,OAAO,GAAI,IAAI,CAAC,SAAS,CAAc,IAAI,EAAE,CAAC;YACpD,MAAM,WAAW,GAAI,IAAI,CAAC,aAAa,CAAY,IAAI,SAAS,CAAC;YACjE,MAAM,KAAK,GAAI,IAAI,CAAC,OAAO,CAAY,IAAI,SAAS,CAAC;YACrD,GAAG,CAAC,YAAY,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC;YAC9C,OAAO,aAAa,OAAO,CAAC,MAAM,gBAAgB,WAAW,IAAI,CAAC;QACpE,CAAC;KACF;CACF,CAAC"}

package/dist/agents/councilApi.d.ts

@@ -0,0 +1,328 @@
+import type { AgentRole } from '../types/index.js';
+import { type ParsedToolCall } from './toolSchemas.js';
+import type { SystemPromptConfig } from '../types/systemTypes.js';
+import type { BrainEvent } from '../shared/events.js';
+import type { ProviderStreamFn } from '../core/AgentHarness.js';
+import { ToolRegistry } from '../core/tools/registry.js';
+import type { CouncilRunMode } from '../council/runMode.js';
+/**
+ * Council members whose tool-emission retry is DISABLED.
+ *
+ * v0.7.7 Opzione B put 'nettun' here because its contract (12 createTask
+ * + 1 createMilestone = 13+ sequential calls) exceeded what composer-2.5
+ * could persist in the 240s budget, making the retry a pure waste.
+ *
+ * v0.7.8 removes 'nettun': the plan contract is now satisfiable with a
+ * SINGLE `createPlan` batch call (phases + nested tasks + milestone in
+ * one emission), so the forced retry has the same 1-call budget that
+ * already works reliably for Minosse and Lucifero. The set stays
+ * exported as the opt-out mechanism for future members.
+ */
+export declare const NON_RETRY_AGENTS: ReadonlySet<string>;
+export type { BrainEvent } from '../shared/events.js';
+export type { AgentMessage, AgentToolSpec, ProviderStreamFn, ProviderDelta, } from '../core/AgentHarness.js';
+/**
+ * Minimal structural interface for a feedback store — matches the
+ * `FeedbackStore` class in `electron/cli/councilFeedback.ts` without
+ * importing it (keeps the core free of CLI-side deps).
+ *
+ * Used by `runCouncilPure` to opt-in to feedback-driven specialist ordering
+ * via the `.ranked()` method (Task: council integration, v3-I deferred).
+ */
+export interface FeedbackStoreLike {
+    /**
+     * Return a NEW array sorted by feedback score, descending.
+     * Members with no feedback are placed last, ordered by id ascending.
+     */
+    ranked<T extends {
+        id: string;
+    }>(items: T[]): T[];
+}
+export interface PureCouncilConfig {
+    apiKey: string;
+    glmApiKey?: string;
+    provider?: string;
+    model: string;
+    councilSize: number;
+    debateMode: boolean;
+    ragContext: string;
+    workspaceContext: string;
+    completedAgentIds?: string[];
+    existingOutputs?: {
+        name: string;
+        role: string;
+        content: string;
+    }[];
+    aiConfig?: SystemPromptConfig;
+    agentModels?: Record<string, {
+        providerId: string;
+        model: string;
+    }>;
+    customProviders?: Array<{
+        id: string;
+        baseUrl: string;
+        authStyle: 'openai' | 'anthropic';
+        models: string[];
+    }>;
+    providerApiKeys?: Record<string, string>;
+    /**
+     * Optional per-call member remap (Task I.3 close-out).
+     *
+     * When set (non-empty), `swapMembers(agents, memberSwap)` is applied
+     * immediately after `getCouncilAgents()` and BEFORE filtering into
+     * specialists / oracle / chairman. Useful for replacing `oracle` with a
+     * custom critic on the fly. Throws `UnknownMemberError` on typo in either
+     * side of the mapping.
+     *
+     * Backward-compat: when omitted, behavior is identical to pre-integration.
+     *
+     * @see swapMembers in src/agents/roles.ts
+     */
+    memberSwap?: Record<string, string>;
+    /**
+     * Optional feedback store for specialist ordering (Task I.2 close-out).
+     *
+     * When set, `feedbackStore.ranked(specialists)` is applied AFTER the swap
+     * filter and BEFORE the specialists loop. Only specialists are ranked —
+     * oracle (debate-mode review) and chairman (synthesis) keep their fixed
+     * positions. This preserves the existing semantics of the council while
+     * letting good-rated specialists go first.
+     *
+     * Backward-compat: when omitted, specialists run in their default order.
+     */
+    feedbackStore?: FeedbackStoreLike;
+    /** Provider stream function (injected for testability). MUST yield ProviderDelta. */
+    providerStream: ProviderStreamFn;
+    /** Optional event bus for emitting BrainEvents alongside the returned iterable. */
+    eventBus?: import('../shared/eventBus.js').EventBus;
+    /** Optional session id. Defaults to a UUID. */
+    sessionId?: string;
+    /**
+     * Optional tool registry. When provided, each council member (specialist
+     * and oracle) is given access to the registry via AgentHarness — tool_call
+     * deltas trigger real tool execution and emit tool_execution_end events.
+     * Without it, the council is text-only (legacy behavior).
+     *
+     * @see electron/main/core/AgentHarness.ts — `toolRegistry` field
+     * @see electron/cli/toolRegistry.ts — `createBuiltinToolRegistry()`
+     */
+    tools?: ToolRegistry;
+    /**
+     * Max tool calls per member per turn. Enforced by truncating extra
+     * tool_execution_start events to `tool_call_skipped` after this limit.
+     * Default: 5. Set to 0 to disable tools entirely (overrides `tools`).
+     */
+    maxToolCallsPerTurn?: number;
+    /** Council run mode. Default: `implementation`. */
+    runMode?: CouncilRunMode;
+}
+export interface PureCouncilCallbacks {
+    onAgentStart?: (agent: AgentRole) => void;
+    onAgentChunk?: (agent: AgentRole, chunk: string) => void;
+    onAgentDone?: (agent: AgentRole, content: string, thinking?: string) => void;
+    onSynthesisStart?: () => void;
+    onSynthesisChunk?: (chunk: string) => void;
+    onSynthesisDone?: (content: string, toolCalls?: ParsedToolCall[], thinking?: string) => void;
+    /**
+     * Fired after every council member (specialist, oracle, chairman) completes
+     * its run, with the accumulated cost for that member (Task I.1, v3-I).
+     * The same payload is also yielded as a `member_cost` BrainEvent in the
+     * main event stream so JSONL sidecars and live consumers stay consistent.
+     *
+     * When the provider does not send `usage` (some don't honor
+     * `stream_options.include_usage`), the token fields are 0. Tool calls
+     * are counted from `tool_execution_start` events. Duration is wall-clock
+     * around the member's AgentHarness run.
+     */
+    onMemberCost?: (cost: {
+        memberId: string;
+        name: string;
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        durationMs: number;
+        toolCalls: number;
+        errored: boolean;
+    }) => void;
+}
+export interface ClarificationRequest {
+    question: string;
+    choices?: string[];
+    context?: string;
+}
+export declare function parseClarificationRequest(text: string): ClarificationRequest | null;
+export declare function parseThinking(text: string): string;
+export declare function cleanAgentContent(text: string): string;
+/**
+ * PURE council orchestration. Loops through specialists, optionally runs
+ * the oracle (debate mode), then runs the chairman synthesis.
+ *
+ * Each agent invocation creates an AgentHarness internally that consumes
+ * the providerStream and emits BrainEvents. The orchestrator aggregates
+ * text deltas into a single message per agent.
+ *
+ * Returns AsyncIterable<BrainEvent> for the full council run.
+ */
+export declare function runCouncilPure(userMessage: string, config: PureCouncilConfig, callbacks?: PureCouncilCallbacks): AsyncIterable<BrainEvent>;
+export interface ToolEmissionRequirement {
+    /** Tool name, e.g. 'createDocument'. */
+    name: string;
+    /** Minimum number of times this tool must have been emitted. */
+    min: number;
+}
+export interface ToolEmissionCheckResult {
+    /** True when every requirement is satisfied. */
+    ok: boolean;
+    /** Human-readable list of unmet requirements (empty when ok=true). */
+    missing: string[];
+}
+/**
+ * Pure helper: given the list of tool names a member emitted during its
+ * turn, and a list of requirements, return whether all requirements are
+ * met.
+ */
+export declare function checkMemberToolEmissions(_memberId: string, emittedToolNames: string[], requirements: ToolEmissionRequirement[]): ToolEmissionCheckResult;
+/**
+ * v0.7.8 — Per-member tool-emission requirement SETS for the design-phase
+ * council run. The outer array is an OR of alternatives: the member's turn
+ * is complete when ANY one set is fully satisfied. The FIRST set is the
+ * preferred contract — its unmet requirements drive the warning message
+ * and the forced-retry tool list.
+ *
+ * Nettuno has two ways to satisfy its contract:
+ *   1. (preferred) ONE `createPlan` batch call — phases + nested tasks +
+ *      milestone in a single emission. Retry budget: 1 call, which
+ *      composer-2.5 handles reliably (same shape as the Minosse/Lucifero
+ *      retries that already work).
+ *   2. (legacy) the itemized trio — kept so stronger models (e.g. Opus)
+ *      that emit createPhase/createTask/createMilestone directly are not
+ *      flagged or retried.
+ */
+export declare const DESIGN_PHASE_REQUIREMENT_SETS: Record<string, ToolEmissionRequirement[][]>;
+/**
+ * Preferred (first) requirement set per member — kept as the flat map the
+ * council loops pass to `applyRetryIfMissing` for the retry budget. For
+ * Nettuno this is `createPlan min 1`, so the forced retry advertises ONE
+ * tool with a 1-call budget instead of the old 13+-call itemized contract.
+ */
+export declare const DESIGN_PHASE_REQUIREMENTS: Record<string, ToolEmissionRequirement[]>;
+/**
+ * Pure helper: OR-of-sets variant of {@link checkMemberToolEmissions}.
+ * Returns ok when ANY set is fully satisfied. When none is, the missing
+ * list reflects the FIRST (preferred) set so the warning and the retry
+ * point the model at the cheapest way to comply.
+ */
+export declare function checkMemberToolEmissionSets(memberId: string, emittedToolNames: string[], sets: ToolEmissionRequirement[][]): ToolEmissionCheckResult;
+/**
+ * Run the post-condition check for a member and emit a console.warn when
+ * any required tool was not emitted the minimum number of times. Returns
+ * the check result so callers can act on it (Pass 3 may add automatic
+ * retry; for now we only warn).
+ */
+export declare function enforceDesignPhaseToolEmissions(memberId: string, emittedToolNames: string[]): ToolEmissionCheckResult;
+/**
+ * Maximum number of forced retry turns per council member. Cap of 1
+ * keeps the worst-case council latency bounded (a single extra turn per
+ * member × 4 design-phase members ≈ 30-60 s on top of the base run).
+ * Going above 1 tends to produce hallucinated tool arguments because
+ * the model has already spent its "tool budget" on exploration.
+ */
+export declare const MAX_RETRY_PER_MEMBER = 1;
+/**
+ * Pure helper: should the council loop spin up one more forced turn for
+ * this member to recover the missing tool emissions?
+ *
+ * Returns true when:
+ *   - at least one tool is still missing after the post-condition check, AND
+ *   - the retry budget for this member has not been exhausted.
+ *
+ * Returns false otherwise. Tested as a pure function so the council
+ * loop can branch on the answer without coupling to AgentHarness.
+ */
+export declare function shouldRetryMember(missingToolNames: string[], attemptsSoFar: number): boolean;
+/**
+ * Build the one-line prompt that the retry turn sends to the model.
+ * The shape matters: the model is primed by its role prompt to produce
+ * prose, so the retry prompt must be unambiguous, imperative, and
+ * scoped to ONLY the missing tools.
+ *
+ * Format: "You did not emit: <names>. Call <names> NOW with concrete
+ * arguments. No prose."
+ *
+ * Multiple tools are listed comma-separated in the same call so the
+ * model can satisfy them in a single tool_calls turn (which is the
+ * cheapest path through AgentHarness).
+ */
+export declare function buildRetryPrompt(missingToolNames: string[]): string;
+export declare function runRetryTurnForMember(args: {
+    agent: AgentRole;
+    missingToolNames: string[];
+    /**
+     * Per-tool minimum emission count. The retry budget is the SUM of these
+     * values (not just the number of distinct missing tools), because
+     * requirements like `createTask min: 12` need 12 separate calls even
+     * though only 1 distinct tool is missing. If omitted, the budget
+     * defaults to `missingToolNames.length` (suitable for tools like
+     * createDocument that need only one call).
+     */
+    minPerTool?: Record<string, number>;
+    executableTools: ReadonlySet<string> | null;
+    userMessage: string;
+    ragContext: string;
+    workspaceContext: string;
+    priorOutputs: {
+        name: string;
+        role: string;
+        content: string;
+    }[];
+    aiConfig?: SystemPromptConfig;
+    sessionId: string;
+    effectiveModel: string;
+    effectiveProvider: string;
+    eventBus?: BrainEvent['sessionId'] extends string ? unknown : never;
+    toolRegistry?: unknown;
+    providerStream: ProviderStreamFn;
+    runMode?: CouncilRunMode;
+}): AsyncGenerator<BrainEvent, string[], void>;
+/**
+ * Shared retry orchestrator used by specialist, oracle, and chairman
+ * loops. Given the post-condition check result, decides whether to
+ * spin up a forced retry turn, and if so yields the events from that
+ * turn back to the caller (so the UI sees them) while mutating the
+ * shared `emittedToolNames` array (so the next post-condition check
+ * sees the union of original + retry emissions).
+ *
+ * The retry turn is skipped when:
+ *   - the check passed (no missing tools), OR
+ *   - the retry budget for this member is exhausted (shouldRetryMember).
+ *
+ * On retry failure (network error, model error, etc.) the function logs
+ * the error and continues — it never throws. The next post-condition
+ * check will simply re-warn.
+ */
+export declare function applyRetryIfMissing(args: {
+    agent: AgentRole;
+    check: ToolEmissionCheckResult;
+    /**
+     * Original per-member requirements. Used to compute the retry budget
+     * (sum of `min` for each missing tool) so the model can satisfy all
+     * minimums in one tool_calls turn. If omitted, defaults to 1 per
+     * distinct missing tool.
+     */
+    requirements?: ToolEmissionRequirement[];
+    emittedToolNames: string[];
+    executableNames: ReadonlySet<string> | null;
+    sessionId: string;
+    userMessage: string;
+    agentOutputs: {
+        name: string;
+        role: string;
+        content: string;
+    }[];
+    config: PureCouncilConfig;
+    effectiveProvider: string;
+    effectiveModel: string;
+    /** Callback to bump the per-member tool-call counter on each retry emission. */
+    onToolCall: () => void;
+}): AsyncGenerator<BrainEvent, void, void>;
+//# sourceMappingURL=councilApi.d.ts.map

package/dist/agents/councilApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"councilApi.d.ts","sourceRoot":"","sources":["../../src/agents/councilApi.ts"],"names":[],"mappings":"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"}