@mrpatronz/nexusflow 2.9.0 → 2.10.0

package/dist/static-resources/workflows/cost-aware-sol-luna.md

@@ -0,0 +1,95 @@
+# Cost-Aware Sol Control + Luna Worker
+
+Use a cheaper Luna/max worker for bounded implementation and a more capable,
+expensive Sol worker for independent review in a fresh context. Accepted review
+feedback returns to the same cheaper builder until the explicit acceptance
+criteria are met.
+
+## Capability boundary
+
+This is an advisory coordination strategy. ContextSpace stores and injects these
+instructions but does not itself launch roles, enforce model, cost tier, or
+reasoning-effort selection, guarantee provider pricing/capability, create a
+fresh reviewer context, track acceptance, or wait for provider rate-limit
+resets. The developer or selected agent harness must perform and verify those
+controls. “Cheaper” and “more capable/expensive” describe the requested role
+relationship; they are not a claim about a provider's current pricing or
+models. If the harness cannot assign the required role settings, create an
+independent context, or observe the safety guard, stop and ask the human
+instead of claiming this strategy was enforced.
+
+## Required role configuration
+
+| Role | Cost/capability target | Model | Reasoning effort | Workspace access |
+| --- | --- | --- | --- | --- |
+| Inspector and planner | Read-only planning gate | `gpt-5.6-sol` | `high` or above | Read-only |
+| Implementation builder | Cheaper model | `gpt-5.6-luna` | `max` | Workspace write |
+| Independent reviewer | More capable/expensive model | `gpt-5.6-sol` | `high` or above | Read-only |
+
+The coordinator may be the inspector and planner. The reviewer must start with
+a fresh context after every builder pass, must not edit files, and must not be
+the builder's conversation. Sol may write code only after explicit human
+approval.
+
+## Acceptance contract
+
+Before the first builder pass, the coordinator records observable acceptance
+criteria in the work packet. At minimum, criteria cover:
+
+- the requested behavior and its important edge cases;
+- targeted tests and relevant regression checks, with the evidence required to
+  pass them;
+- security, data-safety, and capability-boundary invariants; and
+- the exact in-scope paths, non-goals, and documentation obligations.
+
+The reviewer returns one of these explicit verdicts:
+
+- **ACCEPTED** — every required criterion is met with evidence and no
+  unresolved finding violates the contract;
+- **CHANGES REQUESTED** — one or more criteria are unmet, with each actionable
+  finding identified by severity, criterion, evidence, and expected behavior;
+  or
+- **BLOCKED** — the reviewer cannot independently verify the contract (for
+  example, the required context, tests, role, or provider is unavailable).
+
+The coordinator triages findings against the work packet. Only feedback that
+is accepted as in-scope is sent to the same Luna builder; disputed or
+out-of-scope feedback is documented and escalated to the human.
+
+## Workflow
+
+1. **Inspect and plan with Sol**
+   - Read the repository instructions, relevant code, tests, and current diff.
+   - Produce a bounded work packet containing the outcome, exact scope and paths, invariants, acceptance tests, non-goals, risks, and recovery notes.
+   - Split large features into independently verifiable vertical slices. Do not send the worker an open-ended request to explore the whole repository.
+2. **Implement with one Luna/max worker**
+   - Give the worker the work packet plus only the context needed for the current slice.
+   - Keep a single writer. Do not run parallel writers against the same checkout.
+   - Require concise checkpoints listing changed files, verification run, and blockers. Reuse this worker for fixes instead of creating another implementation session.
+3. **Review with fresh Sol**
+   - Freeze the diff and give the reviewer the work packet, changed paths, and verification evidence.
+   - Ask for correctness, security, regression, boundary, and missing-test findings using the verdicts in the acceptance contract. Each finding must include severity, criterion, location, evidence, and expected behavior.
+   - The reviewer reports only; the Luna worker applies accepted fixes.
+4. **Return accepted feedback to Luna**
+   - For **CHANGES REQUESTED**, send only the accepted, in-scope findings to the same Luna builder. Require a checkpoint with changed paths, verification output, and which criteria are now satisfied.
+   - Rerun affected verification after every fix, freeze the new diff, and start another fresh Sol review. Do not silently switch writers or reuse the reviewer's context.
+5. **Terminate or escalate from the verdict**
+   - **ACCEPTED** is the only automatic success/termination path. Finish with the criteria evidence, files changed, checks run, review verdict, and remaining risks.
+   - On **BLOCKED**, a missing role/context/provider, conflicting feedback, or no measurable progress on a repeated finding, pause and ask the human whether to restore the prerequisite, revise the scope/criteria, accept a documented risk, or continue.
+   - Before work starts, the coordinator must record at least one finite safety guard (for example an iteration, wall-clock, token, or cost budget) and checkpoint each pass against it. Reaching the guard pauses the workflow and requires an explicit human decision; it never auto-accepts, silently continues, or silently abandons unmet criteria. A guard is a safety escalation, not a substitute for acceptance, so there is no arbitrary fixed correction-loop cutoff.
+
+## Rate-limit and cost rules
+
+- Reuse active role sessions and checkpoint before pausing. A timeout or delayed response is not permission to create a duplicate agent.
+- If a role is rate-limited, preserve its work packet and wait for that role to become available or ask the human for a named substitute. Do not claim an acceptance verdict while the independent reviewer is unavailable. Manual work may continue from the same packet only when it preserves the role and acceptance contract.
+- If Luna is unavailable, ask the human before using `gpt-5.6-terra` at `max` as the implementation worker.
+- Never silently upgrade implementation to Sol. If Sol is unavailable for planning or independent review, pause at that gate or request explicit human approval for a named substitute.
+- Keep raw logs, repeated repository summaries, and broad file dumps out of handoffs. Prefer exact paths, decisions, diffs, and test results.
+
+## Manual cooperation
+
+A developer may perform any role manually. Record the same work packet, safety
+guard, builder checkpoints, and review verdicts so another developer or agent
+can take the next turn without reconstructing the session. In a Workroom,
+publish the strategy and update shared plan, decision, handoff, and workflow
+evidence; source code and diffs remain in each developer's local checkout.

package/dist/storage/db.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @module storage/db
+ * Server-side SQLite persistence using Node's built-in `node:sqlite` DatabaseSync.
+ * Gracefully falls back to a durable in-process store when running on Node < 22.5.
+ * Stores chat threads, turns, and approval records durably in ~/.nexusflow/nexusflow.db.
+ */
+export interface IDatabaseSync {
+    exec(sql: string): void;
+    prepare(sql: string): {
+        run(...args: any[]): any;
+        get(...args: any[]): any;
+        all(...args: any[]): any[];
+    };
+    close(): void;
+}
+export interface StoredChatMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    ts?: number;
+    kind?: 'error' | 'note';
+    executionProfile?: string;
+    images?: string[];
+    filesChanged?: string[];
+}
+export interface StoredChatThread {
+    workspaceId: string;
+    providerId: string | null;
+    sessions: Record<string, {
+        id: string;
+        started: boolean;
+        model?: string;
+        effort?: string;
+    }>;
+    profilesByProvider: Record<string, string>;
+    modelsByProvider: Record<string, string>;
+    effortsByProvider: Record<string, string>;
+    messages: StoredChatMessage[];
+    updatedAt: number;
+}
+export interface StoredApproval {
+    id: string;
+    workspaceId: string;
+    tool: string;
+    input: Record<string, unknown>;
+    description?: string;
+    decision: 'pending' | 'allow' | 'deny';
+    createdAt: number;
+    resolvedAt?: number;
+}
+/**
+ * Lightweight in-memory/JSON database fallback used when node:sqlite is not
+ * present in the runtime (e.g. Node 20 or earlier).
+ */
+export declare class FallbackDatabase implements IDatabaseSync {
+    private targetPath;
+    private threads;
+    private turns;
+    private approvals;
+    private inTransaction;
+    private stagingThreads;
+    private stagingTurns;
+    private stagingApprovals;
+    constructor(targetPath: string);
+    private getJsonPaths;
+    private getActiveThreads;
+    private getActiveTurns;
+    private getActiveApprovals;
+    private onMutation;
+    private loadFromDisk;
+    private saveToDisk;
+    exec(sql: string): void;
+    prepare(sql: string): {
+        run(...args: any[]): any;
+        get(...args: any[]): any;
+        all(...args: any[]): any[];
+    };
+    close(): void;
+}
+export declare function getDefaultDbPath(): string;
+export declare function initDatabase(dbPath?: string): IDatabaseSync;
+export declare function closeDatabase(): void;
+export declare function saveChatThread(thread: Omit<StoredChatThread, 'updatedAt'>, db?: IDatabaseSync): void;
+export declare function loadChatThread(workspaceId: string, db?: IDatabaseSync): StoredChatThread | null;
+export declare function clearChatThread(workspaceId: string, db?: IDatabaseSync): void;
+export declare function recordApproval(approval: {
+    id: string;
+    workspaceId: string;
+    tool: string;
+    input: Record<string, unknown>;
+    description?: string;
+}, db?: IDatabaseSync): void;
+export declare function resolveApproval(id: string, decision: 'allow' | 'deny', db?: IDatabaseSync): void;
+export declare function getPendingApprovals(workspaceId: string, db?: IDatabaseSync): StoredApproval[];
+//# sourceMappingURL=db.d.ts.map

package/dist/storage/db.d.ts.map

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