opencandle 0.4.0 → 0.6.0

package/dist/workflows/options-screener.d.ts

@@ -1,6 +1,3 @@
 import type { OptionsScreenerSlots, SlotResolution } from "../routing/types.js";
-import type { WorkflowPlan } from "./types.js";
 import type { WorkflowDefinition } from "../runtime/prompt-step.js";
 export declare function buildOptionsScreenerWorkflowDefinition(resolution: SlotResolution<OptionsScreenerSlots>): WorkflowDefinition;
-/** @deprecated Use buildOptionsScreenerWorkflowDefinition instead */
-export declare function buildOptionsScreenerWorkflow(resolution: SlotResolution<OptionsScreenerSlots>): WorkflowPlan;

package/dist/workflows/options-screener.js

@@ -2,7 +2,68 @@ import { buildOptionsScreenerPrompt } from "../prompts/workflow-prompts.js";
 import { promptStep } from "../runtime/prompt-step.js";
 export function buildOptionsScreenerWorkflowDefinition(resolution) {
     const s = resolution.resolved;
-    const contractType = s.direction === "bullish" ? "calls" : "puts";
+    const isProtectivePutContext = s.optionStrategy === "protective_put";
+    const contractType = s.direction === "bullish" && !isProtectivePutContext ? "calls" : "puts";
+    const horizonPhrase = describeDteTarget(s.dteTarget);
+    const isCoveredCallContext = !isProtectivePutContext &&
+        (s.optionStrategy === "covered_call" ||
+            s.costBasis !== undefined ||
+            (s.catalystSymbols?.length ?? 0) > 0);
+    const rankingInstruction = isProtectivePutContext
+        ? "Rank by protection per dollar of premium, expiration fit, moneyness, hedge floor, live liquidity, and premium as a percent of the stock position."
+        : isCoveredCallContext
+            ? "Rank by premium collected, strike above cost basis, assignment risk, event risk, live liquidity, and probability of expiring out of the money."
+            : `Rank by ${s.objective}: balance premium cost, delta exposure, and probability of profit. Only include contracts with |delta| >= 0.20.`;
+    const maxPremiumInstruction = s.maxPremium !== undefined
+        ? ` Do not rank contracts above the user's max premium of $${s.maxPremium.toLocaleString("en-US")} unless no contracts under that cap are liquid; if so, say the cap could not be met.`
+        : "";
+    const riskInstruction = isProtectivePutContext
+        ? "Include protective-put hedge risks: premium decay/cost, imperfect hedge before the strike, liquidity, and opportunity cost. Long protective puts do not have short-option assignment risk."
+        : isCoveredCallContext
+            ? "Include covered-call sale risks: assignment risk, upside is capped at the strike plus premium, share-price downside in the owned stock less premium received, IV/event risk, and exit liquidity. Do not say max loss = premium or describe max loss as the option premium paid."
+            : "Include risk caveats: max loss = premium, IV crush risk, time decay (theta).";
+    const coveredCallFallback = isCoveredCallContext
+        ? `
+	Covered-call fallback:
+- Treat this as selling covered calls against an existing ${s.symbol} share position, not buying calls.
+- Briefly state that you are treating ${s.symbol} as the held ticker because the user phrased it as an existing holding. If they meant memory exposure or a different ticker, tell them to clarify and do not silently switch to another underlying.
+- If retrieved contracts have zero bid/ask, zero open interest, or otherwise unusable live quotes, do not stop at "cannot rank."
+- This fallback overrides the normal ranking/table requirements and the delta >= 0.20 filter.
+- Do NOT conclude with "I cannot provide a recommendation" in this fallback case.
+- The final answer MUST include:
+  - "Best action:" no trade unless the user's broker shows a real bid.
+  - "Conditional candidate:" a conditional limit-order candidate using the user's cost basis and catalyst context.
+- If you cannot compute an exact premium, say "premium: use live broker bid/ask" rather than omitting the candidate.
+- Choose a conditional candidate strike above cost basis that the user would accept for assignment, prefer near-term expirations around the catalyst, and label it as conditional on live bid/ask and premium collected.
+- For the top pick, include the effective assignment sale price (strike + premium collected) and compare it with the ${s.costBasis !== undefined ? `$${s.costBasis}` : "user's"} cost basis.
+- Include return-if-assigned when cost basis is available: (strike - cost basis + premium received) / cost basis.
+- Verify bid/ask and open interest in the user's broker before trading, even when OC shows live values.
+- Mention the catalyst only as event/sympathy risk; do not switch the underlying away from ${s.symbol}.
+- Do not describe max loss as the option premium paid; covered-call sale risk is assignment risk, upside is capped at strike plus premium, share-price downside in the owned stock less premium received, IV/event risk, and poor exit liquidity.
+- If the tool reports closed_market_or_stale_quotes, do not treat zero bid/ask as confirmed live illiquidity; say the chain was checked outside regular options trading and recheck after regular options trading opens.
+- Required fallback format:
+  Interpretation: Treating ${s.symbol} as the held ticker because you phrased it as an existing position. If you meant ${s.symbol} as memory exposure or another ticker, clarify before trading.
+  Best action: ...
+  Conditional candidate: ...
+  Why: ...
+  Risk: ...
+`
+        : "";
+    const coveredCallNoDataGuidance = isCoveredCallContext
+        ? "- For covered-call requests in that no-data fallback, explain how to evaluate covered calls: compare 1-week vs 2-week theta/gamma tradeoffs, use delta as an assignment-risk proxy, avoid strikes where assignment would violate the user's cost basis unless premium offsets it, calculate static premium yield and return-if-assigned, and flag catalyst/IV-crush risk."
+        : "";
+    const protectivePutFallback = isProtectivePutContext
+        ? `
+Protective-put requirements:
+- Treat this as buying puts to hedge an existing long ${s.symbol} share position, not buying calls.
+- The final answer MUST discuss hedge floor, premium as a percent of position value, expiration fit, moneyness, and liquidity.
+- If share quantity is available, translate shares into approximate contract count using 1 put contract per 100 shares.
+- If share quantity is available, state total premium for the required number of contracts.
+- For cost-sensitive requests, explain the tradeoff between cheaper lower-strike puts and weaker protection.
+- Mention lower-cost alternatives such as collars or put spreads when outright put premium is high.
+- Do not frame assignment risk like a short option sale.
+`
+        : "";
     return {
         workflowType: "options_screener",
         steps: [
@@ -13,19 +74,23 @@ export function buildOptionsScreenerWorkflowDefinition(resolution) {
             promptStep("rank_and_present", "Rank and present top contracts", `Now rank and present the top ${contractType} for ${s.symbol}. You MUST produce a final text response — never end this turn with only tool calls.
 
 1. From the option chain data already fetched, select the top 3-5 contracts matching: ${s.moneynessPreference} strikes, DTE near ${s.dteTarget}, with ${s.liquidityMinimum}.
-2. Rank by ${s.objective}: balance premium cost, delta exposure, and probability of profit. Only include contracts with |delta| >= 0.20.
-3. Present a table: strike, expiry, premium, delta, IV, open interest, bid-ask spread.
+2. ${rankingInstruction}${maxPremiumInstruction}
+3. Present a table: strike, expiry, premium, delta, gamma, theta, vega, rho, IV, open interest, bid-ask spread.
 4. Explain why the #1 pick is ranked highest.
-5. State all assumptions used (which were defaults vs user-specified vs saved preferences).
-6. Include risk caveats: max loss = premium, IV crush risk, time decay (theta).
+5. Reproduce the exact Assumptions block from the initial prompt; keep the provenance label text intact and do not shorten it to "Assumptions:".
+6. State the requested option horizon in plain language (${horizonPhrase}) in the bottom line or table intro; use the user's horizon wording or approximate DTE window without forcing a fixed sentence.
+7. ${riskInstruction}
 
 If some or all of the option chain fetches returned "⚠ Options chain unavailable" or similar gaps, do NOT abort. Instead:
 - Rank and present whatever contracts you did retrieve from the successful fetches, even if fewer than 3.
-- If no chain data is usable at all, still produce a text response: reproduce the Assumptions block, state which expirations failed, and commit to a next step (e.g. "retry nearest monthly expiration", "use price/technicals instead"). Never end the turn with only tool calls.
+- If no chain data is usable at all, still produce a text response: reproduce the Assumptions block, state which expirations failed, and give actionable fallback guidance for the requested DTE instead of ranking nonexistent contracts. Do not promise to retry later. Never end the turn with only tool calls.
+${coveredCallNoDataGuidance}
+${coveredCallFallback}
+${protectivePutFallback}
 
 Length constraints:
 - Max 1 sentence explaining the #1 pick.
-- Risk caveats: max 3 bullet points.
+- Risk section: max 3 bullets.
 - Keep total response under 30 lines.`, {
                 requiredInputs: ["option_chain"],
                 expectedOutputs: ["ranked_contracts"],
@@ -33,12 +98,21 @@ Length constraints:
         ],
     };
 }
-/** @deprecated Use buildOptionsScreenerWorkflowDefinition instead */
-export function buildOptionsScreenerWorkflow(resolution) {
-    const def = buildOptionsScreenerWorkflowDefinition(resolution);
-    return {
-        initialPrompt: def.steps[0].prompt,
-        followUps: def.steps.slice(1).map((s) => s.prompt),
-    };
+function describeDteTarget(dteTarget) {
+    if (dteTarget === "25_to_45_days")
+        return "25-45 day target, roughly one month";
+    if (dteTarget === "7_to_14_days")
+        return "1-2 week horizon";
+    if (dteTarget === "0_to_7_days")
+        return "event-week or 0-7 day horizon";
+    if (dteTarget === "180_plus_days")
+        return "LEAPS or long-dated horizon";
+    const range = dteTarget.match(/^(\d+)_to_(\d+)_days$/);
+    if (range)
+        return `${range[1]}-${range[2]} day horizon`;
+    const plus = dteTarget.match(/^(\d+)_plus_days$/);
+    if (plus)
+        return `${plus[1]}+ day horizon`;
+    return `${dteTarget} horizon`;
 }
 //# sourceMappingURL=options-screener.js.map

package/dist/workflows/options-screener.js.map

@@ -1 +1 @@
-{"version":3,"file":"options-screener.js","sourceRoot":"","sources":["../../src/workflows/options-screener.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAG5E,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAEvD,MAAM,UAAU,sCAAsC,CAAC,UAAgD;IACrG,MAAM,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC;IAC9B,MAAM,YAAY,GAAG,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAElE,OAAO;QACL,YAAY,EAAE,kBAAkB;QAChC,KAAK,EAAE;YACL,UAAU,CAAC,aAAa,EAAE,yBAAyB,EAAE,0BAA0B,CAAC,UAAU,CAAC,EAAE;gBAC3F,cAAc,EAAE,CAAC,QAAQ,CAAC;gBAC1B,eAAe,EAAE,CAAC,cAAc,CAAC;aAClC,CAAC;YACF,UAAU,CAAC,kBAAkB,EAAE,gCAAgC,EAAE,gCAAgC,YAAY,QAAQ,CAAC,CAAC,MAAM;;wFAE3C,CAAC,CAAC,mBAAmB,sBAAsB,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,gBAAgB;aAC7J,CAAC,CAAC,SAAS;;;;;;;;;;;;;sCAac,EAAE;gBAChC,cAAc,EAAE,CAAC,cAAc,CAAC;gBAChC,eAAe,EAAE,CAAC,kBAAkB,CAAC;aACtC,CAAC;SACH;KACF,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,4BAA4B,CAAC,UAAgD;IAC3F,MAAM,GAAG,GAAG,sCAAsC,CAAC,UAAU,CAAC,CAAC;IAC/D,OAAO;QACL,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM;QAClC,SAAS,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;KACnD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"options-screener.js","sourceRoot":"","sources":["../../src/workflows/options-screener.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAG5E,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAEvD,MAAM,UAAU,sCAAsC,CACpD,UAAgD;IAEhD,MAAM,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC;IAC9B,MAAM,sBAAsB,GAAG,CAAC,CAAC,cAAc,KAAK,gBAAgB,CAAC;IACrE,MAAM,YAAY,GAAG,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAC7F,MAAM,aAAa,GAAG,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACrD,MAAM,oBAAoB,GACxB,CAAC,sBAAsB;QACvB,CAAC,CAAC,CAAC,cAAc,KAAK,cAAc;YAClC,CAAC,CAAC,SAAS,KAAK,SAAS;YACzB,CAAC,CAAC,CAAC,eAAe,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,MAAM,kBAAkB,GAAG,sBAAsB;QAC/C,CAAC,CAAC,mJAAmJ;QACrJ,CAAC,CAAC,oBAAoB;YACpB,CAAC,CAAC,gJAAgJ;YAClJ,CAAC,CAAC,WAAW,CAAC,CAAC,SAAS,iHAAiH,CAAC;IAC9I,MAAM,qBAAqB,GACzB,CAAC,CAAC,UAAU,KAAK,SAAS;QACxB,CAAC,CAAC,2DAA2D,CAAC,CAAC,UAAU,CAAC,cAAc,CAAC,OAAO,CAAC,sFAAsF;QACvL,CAAC,CAAC,EAAE,CAAC;IACT,MAAM,eAAe,GAAG,sBAAsB;QAC5C,CAAC,CAAC,4LAA4L;QAC9L,CAAC,CAAC,oBAAoB;YACpB,CAAC,CAAC,iRAAiR;YACnR,CAAC,CAAC,8EAA8E,CAAC;IACrF,MAAM,mBAAmB,GAAG,oBAAoB;QAC9C,CAAC,CAAC;;4DAEsD,CAAC,CAAC,MAAM;wCAC5B,CAAC,CAAC,MAAM;;;;;;;;;uHASuE,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,QAAQ;;;6FAGlF,CAAC,CAAC,MAAM;;;;6BAIxE,CAAC,CAAC,MAAM,oFAAoF,CAAC,CAAC,MAAM;;;;;CAKhI;QACG,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,yBAAyB,GAAG,oBAAoB;QACpD,CAAC,CAAC,2WAA2W;QAC7W,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,qBAAqB,GAAG,sBAAsB;QAClD,CAAC,CAAC;;wDAEkD,CAAC,CAAC,MAAM;;;;;;;CAO/D;QACG,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO;QACL,YAAY,EAAE,kBAAkB;QAChC,KAAK,EAAE;YACL,UAAU,CAAC,aAAa,EAAE,yBAAyB,EAAE,0BAA0B,CAAC,UAAU,CAAC,EAAE;gBAC3F,cAAc,EAAE,CAAC,QAAQ,CAAC;gBAC1B,eAAe,EAAE,CAAC,cAAc,CAAC;aAClC,CAAC;YACF,UAAU,CACR,kBAAkB,EAClB,gCAAgC,EAChC,gCAAgC,YAAY,QAAQ,CAAC,CAAC,MAAM;;wFAEoB,CAAC,CAAC,mBAAmB,sBAAsB,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,gBAAgB;KACrK,kBAAkB,GAAG,qBAAqB;;;;2DAIY,aAAa;KACnE,eAAe;;;;;EAKlB,yBAAyB;EACzB,mBAAmB;EACnB,qBAAqB;;;;;sCAKe,EAC9B;gBACE,cAAc,EAAE,CAAC,cAAc,CAAC;gBAChC,eAAe,EAAE,CAAC,kBAAkB,CAAC;aACtC,CACF;SACF;KACF,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,SAAiB;IAC1C,IAAI,SAAS,KAAK,eAAe;QAAE,OAAO,qCAAqC,CAAC;IAChF,IAAI,SAAS,KAAK,cAAc;QAAE,OAAO,kBAAkB,CAAC;IAC5D,IAAI,SAAS,KAAK,aAAa;QAAE,OAAO,+BAA+B,CAAC;IACxE,IAAI,SAAS,KAAK,eAAe;QAAE,OAAO,6BAA6B,CAAC;IACxE,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;IACvD,IAAI,KAAK;QAAE,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC;IACxD,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IAClD,IAAI,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC;IAC3C,OAAO,GAAG,SAAS,UAAU,CAAC;AAChC,CAAC"}

package/dist/workflows/portfolio-builder.d.ts

@@ -1,6 +1,3 @@
 import type { PortfolioSlots, SlotResolution } from "../routing/types.js";
-import type { WorkflowPlan } from "./types.js";
 import type { WorkflowDefinition } from "../runtime/prompt-step.js";
 export declare function buildPortfolioWorkflowDefinition(resolution: SlotResolution<PortfolioSlots>): WorkflowDefinition;
-/** @deprecated Use buildPortfolioWorkflowDefinition instead */
-export declare function buildPortfolioWorkflow(resolution: SlotResolution<PortfolioSlots>): WorkflowPlan;

package/dist/workflows/portfolio-builder.js

@@ -13,7 +13,8 @@ export function buildPortfolioWorkflowDefinition(resolution) {
 1. Use analyze_correlation across all ${s.positionCount} candidates to check for concentration risk.
 2. Use analyze_risk on each position for volatility and max drawdown.
 3. If correlation is too high (>0.7 between any pair), suggest a replacement to improve diversification.
-4. Confirm the portfolio fits a ${s.riskProfile} risk profile with ${s.timeHorizon} horizon.`, {
+4. If any position's risk metrics undermine its intended role, lower its allocation, replace it with a role-equivalent candidate, or explicitly justify why it remains.
+5. Confirm the portfolio fits a ${s.riskProfile} risk profile with ${s.timeHorizon} horizon.`, {
                 skippable: true,
                 requiredInputs: ["candidate_positions"],
                 expectedOutputs: ["risk_assessment"],
@@ -21,13 +22,16 @@ export function buildPortfolioWorkflowDefinition(resolution) {
             promptStep("synthesize", "Present final portfolio draft", `Present the final portfolio draft as a structured summary:
 - State all assumptions at the top (which parameters were defaults vs user-specified vs saved preferences).
 - Commit to the allocation: concrete percentages per position, not ranges.
-- Present an allocation table: symbol, allocation %, dollar amount ($${s.budget.toLocaleString("en-US")} total), and one-line analyst rationale per position.
+- Present an allocation table: symbol, allocation %, dollar amount ($${s.budget.toLocaleString("en-US")} total), current price used, estimated shares, role, and one-line analyst rationale per position.
+- Add a brief "Why this fits the horizon" summary explaining the growth/stability tradeoff for the ${s.timeHorizon} horizon.
 - Include overall portfolio risk summary: estimated volatility, diversification quality, largest single risk. State an invalidation condition for the draft.
+- Include implementation notes: rebalance cadence, low-cost/liquid implementation, and tax/account caveats where relevant.
 - Suggest what to change for more growth or more safety.
 
 Length constraints:
-- Max 1 sentence of rationale per position in the allocation table.
+- Max 1 sentence of rationale per position in the allocation table; do not paste company descriptions or issuer background.
 - Risk summary: max 3 bullet points.
+- Implementation notes: max 3 bullets.
 - Growth/safety suggestions: max 2 bullet points each.
 - Keep total response under 40 lines.`, {
                 requiredInputs: ["risk_assessment"],
@@ -36,12 +40,4 @@ Length constraints:
         ],
     };
 }
-/** @deprecated Use buildPortfolioWorkflowDefinition instead */
-export function buildPortfolioWorkflow(resolution) {
-    const def = buildPortfolioWorkflowDefinition(resolution);
-    return {
-        initialPrompt: def.steps[0].prompt,
-        followUps: def.steps.slice(1).map((s) => s.prompt),
-    };
-}
 //# sourceMappingURL=portfolio-builder.js.map

package/dist/workflows/portfolio-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"portfolio-builder.js","sourceRoot":"","sources":["../../src/workflows/portfolio-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAGtE,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAEvD,MAAM,UAAU,gCAAgC,CAAC,UAA0C;IACzF,MAAM,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC;IAE9B,OAAO;QACL,YAAY,EAAE,mBAAmB;QACjC,KAAK,EAAE;YACL,UAAU,CAAC,kBAAkB,EAAE,yCAAyC,EAAE,oBAAoB,CAAC,UAAU,CAAC,EAAE;gBAC1G,cAAc,EAAE,CAAC,SAAS,CAAC;gBAC3B,eAAe,EAAE,CAAC,qBAAqB,CAAC;aACzC,CAAC;YACF,UAAU,CAAC,aAAa,EAAE,iCAAiC,EAAE;wCAC3B,CAAC,CAAC,aAAa;;;kCAGrB,CAAC,CAAC,WAAW,sBAAsB,CAAC,CAAC,WAAW,WAAW,EAAE;gBACvF,SAAS,EAAE,IAAI;gBACf,cAAc,EAAE,CAAC,qBAAqB,CAAC;gBACvC,eAAe,EAAE,CAAC,iBAAiB,CAAC;aACrC,CAAC;YACF,UAAU,CAAC,YAAY,EAAE,+BAA+B,EAAE;;;uEAGO,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC;;;;;;;;sCAQjE,EAAE;gBAChC,cAAc,EAAE,CAAC,iBAAiB,CAAC;gBACnC,eAAe,EAAE,CAAC,mBAAmB,CAAC;aACvC,CAAC;SACH;KACF,CAAC;AACJ,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,sBAAsB,CAAC,UAA0C;IAC/E,MAAM,GAAG,GAAG,gCAAgC,CAAC,UAAU,CAAC,CAAC;IACzD,OAAO;QACL,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM;QAClC,SAAS,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;KACnD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"portfolio-builder.js","sourceRoot":"","sources":["../../src/workflows/portfolio-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAGtE,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAEvD,MAAM,UAAU,gCAAgC,CAC9C,UAA0C;IAE1C,MAAM,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC;IAE9B,OAAO;QACL,YAAY,EAAE,mBAAmB;QACjC,KAAK,EAAE;YACL,UAAU,CACR,kBAAkB,EAClB,yCAAyC,EACzC,oBAAoB,CAAC,UAAU,CAAC,EAChC;gBACE,cAAc,EAAE,CAAC,SAAS,CAAC;gBAC3B,eAAe,EAAE,CAAC,qBAAqB,CAAC;aACzC,CACF;YACD,UAAU,CACR,aAAa,EACb,iCAAiC,EACjC;wCACgC,CAAC,CAAC,aAAa;;;;kCAIrB,CAAC,CAAC,WAAW,sBAAsB,CAAC,CAAC,WAAW,WAAW,EACrF;gBACE,SAAS,EAAE,IAAI;gBACf,cAAc,EAAE,CAAC,qBAAqB,CAAC;gBACvC,eAAe,EAAE,CAAC,iBAAiB,CAAC;aACrC,CACF;YACD,UAAU,CACR,YAAY,EACZ,+BAA+B,EAC/B;;;uEAG+D,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC;qGACF,CAAC,CAAC,WAAW;;;;;;;;;;sCAU5E,EAC9B;gBACE,cAAc,EAAE,CAAC,iBAAiB,CAAC;gBACnC,eAAe,EAAE,CAAC,mBAAmB,CAAC;aACvC,CACF;SACF;KACF,CAAC;AACJ,CAAC"}

package/gui/server/ask-user-bridge.ts

@@ -0,0 +1,82 @@
+import type { AskUserHandler } from "../../src/types/index.js";
+
+type AskUserParams = Parameters<AskUserHandler>[0];
+type AskUserResult = Awaited<ReturnType<AskUserHandler>>;
+
+export interface GuiAskUserPrompt extends AskUserParams {
+  id: string;
+  sessionId: string;
+  status: "pending" | "answered" | "cancelled";
+  answer: string | null;
+}
+
+interface PendingPrompt {
+  prompt: GuiAskUserPrompt;
+  resolve: (result: AskUserResult) => void;
+}
+
+export function createAskUserBridge({
+  broadcast,
+  getSessionId,
+}: {
+  broadcast: (message: unknown) => void;
+  getSessionId: () => string;
+}): {
+  ask: AskUserHandler;
+  answer: (id: string, answer: string) => boolean;
+  cancel: (id: string) => boolean;
+  getPrompts: () => GuiAskUserPrompt[];
+} {
+  let nextId = 1;
+  const prompts = new Map<string, GuiAskUserPrompt>();
+  const pending = new Map<string, PendingPrompt>();
+
+  const ask: AskUserHandler = async (params) => {
+    const id = `ask-user-${Date.now()}-${nextId++}`;
+    const prompt: GuiAskUserPrompt = {
+      id,
+      sessionId: getSessionId(),
+      question: params.question,
+      questionType: params.questionType,
+      options: params.options,
+      placeholder: params.placeholder,
+      reason: params.reason,
+      status: "pending",
+      answer: null,
+    };
+    prompts.set(id, prompt);
+    broadcast({ type: "ask_user.prompt", prompt });
+
+    return new Promise<AskUserResult>((resolve) => {
+      pending.set(id, { prompt, resolve });
+    });
+  };
+
+  const resolvePrompt = (id: string, result: AskUserResult): boolean => {
+    const item = pending.get(id);
+    if (!item) return false;
+    pending.delete(id);
+    const prompt: GuiAskUserPrompt = {
+      ...item.prompt,
+      status: result.cancelled ? "cancelled" : "answered",
+      answer: result.cancelled ? null : (result.answer ?? null),
+    };
+    prompts.set(id, prompt);
+    broadcast({ type: "ask_user.resolved", prompt });
+    item.resolve(result);
+    return true;
+  };
+
+  return {
+    ask,
+    answer(id, answer) {
+      return resolvePrompt(id, { answer, cancelled: false });
+    },
+    cancel(id) {
+      return resolvePrompt(id, { answer: null, cancelled: true });
+    },
+    getPrompts() {
+      return [...prompts.values()];
+    },
+  };
+}

package/gui/server/automation-heartbeat.ts

@@ -0,0 +1,97 @@
+import { runLocalAutomationHeartbeat } from "../../src/market-state/local-automation-service.js";
+import { initDefaultDatabase } from "../../src/memory/sqlite.js";
+
+export const DEFAULT_AUTOMATION_HEARTBEAT_MS = 60_000;
+export const MIN_AUTOMATION_HEARTBEAT_MS = 5_000;
+
+export function normalizeAutomationHeartbeatMs(raw: string | undefined): number {
+  if (raw == null || raw.trim() === "") return DEFAULT_AUTOMATION_HEARTBEAT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < MIN_AUTOMATION_HEARTBEAT_MS)
+    return DEFAULT_AUTOMATION_HEARTBEAT_MS;
+  return Math.floor(parsed);
+}
+
+export function createAutomationHeartbeatRunner(
+  run: (checkAlerts: boolean) => Promise<void>,
+): (checkAlerts: boolean) => Promise<boolean> {
+  let inFlight = false;
+  return async (checkAlerts: boolean) => {
+    if (inFlight) return false;
+    inFlight = true;
+    try {
+      await run(checkAlerts);
+      return true;
+    } finally {
+      inFlight = false;
+    }
+  };
+}
+
+type IntervalHandle = ReturnType<typeof setInterval>;
+type SetIntervalFn = (callback: () => void, ms: number) => IntervalHandle;
+type ClearIntervalFn = (handle: IntervalHandle) => void;
+
+export interface LocalAutomationHeartbeat {
+  start(): void;
+  stop(): void;
+}
+
+export interface LocalAutomationHeartbeatOptions {
+  role: string;
+  getSessionId: () => string;
+  intervalMs: number;
+  initDatabase?: typeof initDefaultDatabase;
+  runHeartbeat?: typeof runLocalAutomationHeartbeat;
+  setIntervalFn?: SetIntervalFn;
+  clearIntervalFn?: ClearIntervalFn;
+  warn?: (message: string) => void;
+}
+
+export function createLocalAutomationHeartbeat({
+  role,
+  getSessionId,
+  intervalMs,
+  initDatabase = initDefaultDatabase,
+  runHeartbeat = runLocalAutomationHeartbeat,
+  setIntervalFn = setInterval,
+  clearIntervalFn = clearInterval,
+  warn = (message) => console.warn(message),
+}: LocalAutomationHeartbeatOptions): LocalAutomationHeartbeat {
+  let automationHeartbeat: IntervalHandle | null = null;
+
+  async function executeGuiAutomationHeartbeat(checkAlerts: boolean): Promise<void> {
+    const db = initDatabase();
+    try {
+      await runHeartbeat(db, {
+        ownerId: `gui:${getSessionId()}`,
+        ownerKind: "writer",
+        ttlSeconds: Math.max(90, Math.ceil((intervalMs * 2) / 1000)),
+        checkAlerts,
+      });
+    } catch (error) {
+      warn(
+        `Local automation heartbeat failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    } finally {
+      db.close();
+    }
+  }
+
+  const runGuiAutomationHeartbeat = createAutomationHeartbeatRunner(executeGuiAutomationHeartbeat);
+
+  function start(): void {
+    if (role !== "writer") return;
+    void runGuiAutomationHeartbeat(true);
+    automationHeartbeat = setIntervalFn(() => void runGuiAutomationHeartbeat(true), intervalMs);
+  }
+
+  function stop(): void {
+    if (automationHeartbeat) {
+      clearIntervalFn(automationHeartbeat);
+      automationHeartbeat = null;
+    }
+  }
+
+  return { start, stop };
+}

package/gui/server/background-quotes.ts

@@ -1,5 +1,10 @@
-import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import type { SessionEntry, SessionManager } from "@earendil-works/pi-coding-agent";
+import { getAllTools } from "../../src/tools/index.js";
+import { invokeToolFromUi } from "./invoke-tool.js";
+import { projectDashboard } from "./projector.js";
+
+export const BACKGROUND_QUOTE_POLL_INTERVAL_MS = 30_000;
 
 export interface BackgroundQuoteRefresh {
   symbol: string;
@@ -29,3 +34,94 @@ export class BackgroundQuoteRefreshes {
     return [...entries, ...this.entriesBySymbol.values()];
   }
 }
+
+type IntervalHandle = ReturnType<typeof setInterval>;
+type SetIntervalFn = (callback: () => void, ms: number) => IntervalHandle;
+type ClearIntervalFn = (handle: IntervalHandle) => void;
+
+export interface BackgroundQuotePoller {
+  updatePoller(): void;
+  pollVisibleQuotes(): Promise<void>;
+  stop(): void;
+}
+
+export interface BackgroundQuotePollerOptions {
+  getClientCount: () => number;
+  getSessionManager: () => SessionManager;
+  refreshes: BackgroundQuoteRefreshes;
+  broadcastState: () => void;
+  getTools?: typeof getAllTools;
+  invokeTool?: typeof invokeToolFromUi;
+  setIntervalFn?: SetIntervalFn;
+  clearIntervalFn?: ClearIntervalFn;
+  warn?: (message: string) => void;
+}
+
+export function createBackgroundQuotePoller({
+  getClientCount,
+  getSessionManager,
+  refreshes,
+  broadcastState,
+  getTools = getAllTools,
+  invokeTool = invokeToolFromUi,
+  setIntervalFn = setInterval,
+  clearIntervalFn = clearInterval,
+  warn = (message) => console.warn(message),
+}: BackgroundQuotePollerOptions): BackgroundQuotePoller {
+  let poller: IntervalHandle | null = null;
+  let quotePollInFlight = false;
+
+  async function pollVisibleQuotes(): Promise<void> {
+    if (quotePollInFlight) return;
+    quotePollInFlight = true;
+    try {
+      const sessionManager = getSessionManager();
+      const state = projectDashboard(sessionManager.getEntries(), sessionManager.getSessionId());
+      const tool = getTools().find((candidate) => candidate.name === "get_stock_quote");
+      if (!tool) return;
+      for (const row of state.watchlist.filter((item) => item.pinned || item.quote)) {
+        const result = await invokeTool(
+          sessionManager,
+          tool,
+          { symbol: row.symbol },
+          "background",
+          { recordTranscript: false },
+        );
+        refreshes.upsert({
+          symbol: row.symbol,
+          toolName: tool.name,
+          args: { symbol: row.symbol },
+          value: result.result.details,
+          content: result.result.content,
+          isError: result.isError,
+        });
+      }
+      broadcastState();
+    } catch (error) {
+      warn(
+        `Background quote refresh failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    } finally {
+      quotePollInFlight = false;
+    }
+  }
+
+  function updatePoller(): void {
+    if (getClientCount() > 0 && !poller) {
+      poller = setIntervalFn(() => void pollVisibleQuotes(), BACKGROUND_QUOTE_POLL_INTERVAL_MS);
+    }
+    if (getClientCount() === 0 && poller) {
+      clearIntervalFn(poller);
+      poller = null;
+    }
+  }
+
+  function stop(): void {
+    if (poller) {
+      clearIntervalFn(poller);
+      poller = null;
+    }
+  }
+
+  return { updatePoller, pollVisibleQuotes, stop };
+}

package/gui/server/chat-event-adapter.ts

@@ -1,5 +1,5 @@
-import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { Message, ToolResultMessage } from "@earendil-works/pi-ai";
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { ChatEvent, MessageContent, ToolOutput } from "../shared/chat-events.js";
 
 export interface SessionEventOptions {
@@ -16,6 +16,9 @@ export function sessionEntriesToChatEvents(
   let seq = options.startSeq ?? 1;
   const events: ChatEvent[] = [];
   const seenToolCalls = new Set<string>();
+  // Set by an opencandle-user-input marker: the user's words before a workflow
+  // transform expanded the turn. The next user message renders this instead.
+  let pendingOriginalInput: string | null = null;
   const updatedAt = options.updatedAt ?? entries.at(-1)?.timestamp ?? new Date().toISOString();
 
   events.push({
@@ -27,12 +30,17 @@ export function sessionEntriesToChatEvents(
   });
 
   for (const entry of entries) {
+    if (isOriginalInputEntry(entry)) {
+      pendingOriginalInput = originalInputText(entry);
+      continue;
+    }
+
     if (entry.type === "custom_message") {
       const messageId = entry.id;
-      events.push({ type: "message.created", messageId, role: "assistant", seq: seq++ });
       events.push({
-        type: "message.completed",
+        type: "custom.message",
         messageId,
+        customType: String((entry as { customType?: unknown }).customType || "custom"),
         content: [{ type: "text", text: customMessageText(entry.content) }],
         seq: seq++,
       });
@@ -48,9 +56,10 @@ export function sessionEntriesToChatEvents(
       events.push({
         type: "message.completed",
         messageId,
-        content: [{ type: "text", text: messageText(message.content) }],
+        content: [{ type: "text", text: pendingOriginalInput ?? messageText(message.content) }],
         seq: seq++,
       });
+      pendingOriginalInput = null;
       continue;
     }
 
@@ -109,6 +118,20 @@ export function sessionEntriesToChatEvents(
   return events;
 }
 
+export function isOriginalInputEntry(entry: SessionEntry): boolean {
+  return (
+    entry.type === "custom" &&
+    (entry as { customType?: unknown }).customType === "opencandle-user-input"
+  );
+}
+
+export function originalInputText(entry: SessionEntry): string | null {
+  const data = (entry as { data?: { original?: unknown } }).data;
+  return typeof data?.original === "string" && data.original.trim().length > 0
+    ? data.original
+    : null;
+}
+
 function customMessageText(content: unknown): string {
   if (typeof content === "string") return content;
   return messageText(content);
@@ -117,16 +140,15 @@ function customMessageText(content: unknown): string {
 function messageText(content: unknown): string {
   if (typeof content === "string") return content;
   if (!Array.isArray(content)) return "";
-  return content
-    .map((part) => typeof part.text === "string" ? part.text : "")
-    .join("");
+  return content.map((part) => (typeof part.text === "string" ? part.text : "")).join("");
 }
 
 function toolOutput(message: ToolResultMessage): ToolOutput {
   const details = message.details;
-  const source = typeof details === "object" && details !== null && "source" in details
-    ? String((details as { source?: unknown }).source ?? "")
-    : undefined;
+  const source =
+    typeof details === "object" && details !== null && "source" in details
+      ? String((details as { source?: unknown }).source ?? "")
+      : undefined;
   return {
     content: message.content,
     details,

package/gui/server/chat-run-session.ts

@@ -0,0 +1,16 @@
+export interface ChatRunSessionConflict {
+  error: string;
+  code: "session_changed";
+}
+
+export function chatRunSessionConflict(
+  expectedSessionId: unknown,
+  activeSessionId: string,
+): ChatRunSessionConflict | null {
+  const expected = typeof expectedSessionId === "string" ? expectedSessionId.trim() : "";
+  if (!expected || expected === activeSessionId) return null;
+  return {
+    error: "The active session changed before this message was sent.",
+    code: "session_changed",
+  };
+}

package/gui/server/gui-session-manager.ts

@@ -0,0 +1,5 @@
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+
+export function createInitialGuiSessionManager(cwd: string, sessionDir?: string): SessionManager {
+  return SessionManager.create(cwd, sessionDir);
+}