kolega-code 0.26.8__tar.gz → 0.26.10__tar.gz

{kolega_code-0.26.8 → kolega_code-0.26.10}/CHANGELOG.md

@@ -6,6 +6,149 @@ This project uses GitHub Releases for detailed generated release notes. This fil
 
 ## Unreleased
 
+## 0.26.10 - 2026-08-05
+
+### Added
+
+- Hosted (server-side) web search for Responses-API providers. On DeepSeek
+  flash and OpenAI gpt-5.x (API key or ChatGPT subscription), kolega can
+  request the provider's own
+  `{"type": "web_search"}` tool: searches and page-opens execute on the
+  provider's servers and the content is injected directly into the model's
+  context (billed as input tokens; the context gauge accounts for it from
+  usage, since the content never reaches the client). Calls render in the
+  transcript as `web_search (hosted)`. Controlled by a new web tool mode —
+  `auto` (default: hosted when the model supports it, else the client tools) /
+  `hosted` / `client` / `off` — via Settings, `KOLEGA_CODE_WEB_SEARCH_MODE`,
+  `ask --web-search`, or the TUI's `/web-search`. When hosted search is active
+  the client-side `web_search`/`web_fetch` tools are not registered; `off`
+  removes all web tools (for sandboxed/benchmark runs). Notes: provider
+  per-search fees, if any, are not modeled in cost reporting (injected tokens
+  are); sessions that used hosted search store a new `web_search_call` history
+  block that older kolega builds cannot load.
+- LSP tools can now be forced on or off for a single launch: `--lsp on|off`
+  on both the TUI and `kolega-code ask`, plus a `KOLEGA_CODE_LSP` env var,
+  resolved flag > env > settings > default-enabled. `--lsp on` overrides a
+  persisted `lsp_enabled=false` without writing back to settings. Turning LSP
+  off now removes the `lsp`/`lsp_edit` tools from the model entirely —
+  previously they stayed registered and could only answer "LSP is not
+  available" — and the Settings LSP status notes when the launch flag is
+  forcing the mode.
+- The per-session scratchpad directory is now exported as `KOLEGA_SCRATCHPAD`
+  to every shell command and eval kernel, so scripts and kernels can reach the
+  session's throwaway workspace by environment variable instead of hardcoding
+  a temp path.
+
+### Changed
+
+- Thinking now renders as a collapsed row in the TUI transcript — `● Thinking
+  · … · 1.2k words` while streaming (a live word counter, never the text),
+  flipping to `● Thought · 12s · 1.2k words` on completion; expand the row to
+  read the full reasoning. Long reasoning turns (DeepSeek flash especially) no
+  longer dominate the transcript with full-height thinking walls.
+- Resumed sessions now restore reasoning as the same collapsed thinking rows,
+  in true interleaved order with tool and hosted web-search rows: Anthropic
+  thinking text, DeepSeek flash's raw chain-of-thought, and OpenAI/ChatGPT
+  reasoning summaries all render (encrypted-only reasoning items have no
+  renderable text and are skipped). Previously reasoning vanished entirely
+  from restored transcripts.
+- The coder prompt now follows a Codex-style final-message contract: the
+  closing report leads with what was delivered and its verified state, stays
+  brief by default with structure scaled to complexity, references files by
+  path instead of re-pasting contents, and never restates the plan step by
+  step. Preambles before tool calls are tightened to a single short line
+  naming the purpose of the next action, and verification effort is bounded —
+  tool results are trusted (no re-reading a file to confirm an edit applied)
+  and verification stops once no remaining check could realistically fail.
+
+### Fixed
+
+- Hosted web-search calls now render in their true position in the TUI
+  transcript. Previously the rows mounted at the bottom and stayed pinned
+  there while post-search reasoning kept streaming into the thinking bubble
+  above them; the stream now closes the open thinking/response segment at
+  each hosted call, so reasoning after a search opens a new bubble below its
+  rows (think → search → think → answer). Resumed sessions now render hosted
+  `web_search (hosted)` rows from history too — previously they were dropped
+  from the restored transcript.
+- `ask --json` no longer emits spurious synthetic message fragments when
+  hosted web search flushes response text mid-stream: the lost-text fallback
+  now applies once at end of turn, and only when the turn produced no
+  assistant message.
+- The context gauge no longer under-reads on `deepseek-v4-flash`. DeepSeek's
+  Responses API silently re-attaches every prior round's reasoning server-side and
+  bills it as input, but the client history held none of it, so the gauge (and the
+  auto-compaction trigger) could run over 100k tokens behind the real billed
+  context on reasoning-heavy sessions. Flash's plain-text reasoning is now retained
+  in history and resent each turn — the same shape Codex replays, deduped by the
+  server so billing is unchanged — which keeps the gauge on the real number and
+  preserves chain-of-thought continuity across session restores. The retained
+  reasoning text also now appears in `ask --json` message payloads (parity with
+  Anthropic thinking text); encrypted-only reasoning from OpenAI/ChatGPT stays
+  stripped as before.
+
+### Security
+
+- Dependency bumps for advisories published 2026-08-03/04: `cryptography`
+  48.0.1 → 50.0.0 (PKCS#7 Bleichenbacher oracle CVE-2026-69247, a name-constraint
+  wildcard bypass CVE-2026-69248, and a path-building DoS CVE-2026-69249) and
+  `aiohttp` 3.14.1 → 3.14.3 (three parser advisories, including an out-of-bounds
+  heap read in the C response parser). Exception: Intel Macs stay on
+  `cryptography` 48.0.1 — every fixed release dropped Intel-mac wheels, and
+  upgrading would break the curl installer there with a Rust+OpenSSL source
+  build — so those three advisories are knowingly accepted on that legacy
+  platform only.
+
+## 0.26.9 - 2026-08-03
+
+### Added
+
+- Settings → Model & Account gains a **Model Slots** section for pinning the fast
+  and thinking models, each with its own provider. Previously these slots were
+  reachable only through CLI flags and environment variables, so in the TUI they
+  silently inherited the active model — every `web_fetch` answering call ran on
+  the main coding model. Slots still inherit by default, and each row now shows
+  which model it currently resolves to.
+- The README now includes a direct invitation to the Kolega Code Discord
+  community.
+
+### Changed
+
+- Settings gains a **Providers** category, first in the rail, holding every model
+  provider's API key and the ChatGPT sign-in, each row labelled with its live
+  credential status. **Model & Account** is renamed **Models** and keeps only what
+  runs. Keys now stage per provider, so credentials for a provider you are not
+  currently using — needed by a fast/thinking slot or an agent-role override — can be
+  entered without switching your main model and switching back. **Test Connection**
+  moves with them and probes the selected provider rather than the active model, so a
+  credential can be checked without running on that provider.
+- **Breaking:** provider and model are now always specified together. `--provider`
+  without `--model` (and the per-role/per-slot equivalents such as
+  `KOLEGA_CODE_FAST_PROVIDER`) is an error instead of silently selecting that
+  provider's default model, and a model named without a provider is rejected rather
+  than assumed to be Anthropic's. Scripts passing only one of the pair need updating;
+  the error names the missing flag. Saved settings are unaffected — the Settings UI
+  always writes both — and a saved model that later leaves the catalog still degrades
+  to the provider's default rather than blocking startup.
+
+### Fixed
+
+- `deepseek-v4-flash` no longer has its reasoning truncated mid-derivation. The
+  64000-token output cap added in 0.26.8 was measured on the chat API for
+  `deepseek-v4-pro` and applied to flash by assumption; flash actually runs to
+  at least 112990 output tokens in a single Responses call. Hard tasks that
+  reason for a long time before acting were cut off at the cap and produced no
+  tool call at all. flash now uses its full published output budget, while pro
+  and the fireworks/openrouter DeepSeek routes keep the 64000 cap where their
+  measured ceilings apply.
+
+### Removed
+
+- The unreachable `DEFAULT_LONG_MODEL`, `DEFAULT_FAST_MODEL`, `DEFAULT_THINKING_MODEL`
+  and their provider constants. No model was ever resolved through them — an unset
+  slot inherits the active model — but they were documented as defaults, which is
+  where "what is my fast model?" became unanswerable.
+
 ## 0.26.8 - 2026-08-03
 
 ### Added

{kolega_code-0.26.8 → kolega_code-0.26.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.26.8
+Version: 0.26.10
 Summary: Multi-agent coding in the terminal
 Project-URL: Homepage, https://kolega-ai.github.io/kolega-code/
 Project-URL: Documentation, https://kolega-ai.github.io/kolega-code/
@@ -231,6 +231,7 @@ Requires-Python: >=3.11
 Requires-Dist: anthropic==0.101.0
 Requires-Dist: beautifulsoup4==4.14.3
 Requires-Dist: cryptography==48.0.1; sys_platform == 'darwin' and platform_machine == 'x86_64'
+Requires-Dist: cryptography==50.0.0; sys_platform != 'darwin' or platform_machine != 'x86_64'
 Requires-Dist: ddgs==9.14.4
 Requires-Dist: fastapi==0.139.2
 Requires-Dist: filelock==3.20.3
@@ -494,6 +495,7 @@ Full documentation lives at **[kolega-ai.github.io/kolega-code](https://kolega-a
 - [Contributing](CONTRIBUTING.md)
 - [Security policy](SECURITY.md)
 - [Issue tracker](https://github.com/kolega-ai/kolega-code/issues)
+- [Discord community](https://discord.gg/kaS8PKKp4)
 
 ## Contributing
 
@@ -504,3 +506,13 @@ privately per [SECURITY.md](SECURITY.md).
 ## License
 
 Released under the [Apache License 2.0](LICENSE).
+
+## Join the community
+
+Building something with Kolega Code, hit a rough edge, or want to shape where
+Gigacode goes next? Come talk to us.
+
+[![Join our Discord](https://img.shields.io/badge/Discord-join%20the%20community-5865F2?logo=discord&logoColor=white)](https://discord.gg/kaS8PKKp4)
+
+**→ [Join the Kolega Code Discord](https://discord.gg/kaS8PKKp4)** — share workflows,
+get help, and hear about releases first.

{kolega_code-0.26.8 → kolega_code-0.26.10}/README.md

@@ -215,6 +215,7 @@ Full documentation lives at **[kolega-ai.github.io/kolega-code](https://kolega-a
 - [Contributing](CONTRIBUTING.md)
 - [Security policy](SECURITY.md)
 - [Issue tracker](https://github.com/kolega-ai/kolega-code/issues)
+- [Discord community](https://discord.gg/kaS8PKKp4)
 
 ## Contributing
 
@@ -225,3 +226,13 @@ privately per [SECURITY.md](SECURITY.md).
 ## License
 
 Released under the [Apache License 2.0](LICENSE).
+
+## Join the community
+
+Building something with Kolega Code, hit a rough edge, or want to shape where
+Gigacode goes next? Come talk to us.
+
+[![Join our Discord](https://img.shields.io/badge/Discord-join%20the%20community-5865F2?logo=discord&logoColor=white)](https://discord.gg/kaS8PKKp4)
+
+**→ [Join the Kolega Code Discord](https://discord.gg/kaS8PKKp4)** — share workflows,
+get help, and hear about releases first.

{kolega_code-0.26.8 → kolega_code-0.26.10}/kolega_code/__init__.py

@@ -151,4 +151,4 @@ __all__ = [
     "parse_git_status_output",
 ]
 
-__version__ = "0.26.8"
+__version__ = "0.26.10"

{kolega_code-0.26.8 → kolega_code-0.26.10}/kolega_code/agent/__init__.py

@@ -51,4 +51,4 @@ __all__ = [
     "ToolExtension",
 ]
 
-__version__ = "0.26.8"
+__version__ = "0.26.10"

{kolega_code-0.26.8 → kolega_code-0.26.10}/kolega_code/agent/baseagent.py

@@ -43,7 +43,15 @@ from kolega_code.llm.exceptions import (
 )
 from kolega_code.llm.instrumented_client import get_output_tokens
 from kolega_code.llm.ledger import HISTORY_ORIGIN, LlmCallOrigin, helper_origin, llm_call_origin
-from kolega_code.llm.models import ImageBlock, Message, MessageHistory, TextBlock, ToolCall, ToolResult
+from kolega_code.llm.models import (
+    ImageBlock,
+    Message,
+    MessageHistory,
+    TextBlock,
+    ToolCall,
+    ToolResult,
+    WebSearchCallBlock,
+)
 from kolega_code.llm.providers.models import TokenCount
 from kolega_code.llm.specs import (
     deepseek_output_token_cap,
@@ -461,6 +469,15 @@ class BaseAgent(LogMixin):
         # tool) and used by _unsupported_attachment_message to reject image
         # attachments for non-vision models with a clear message.
         self.supports_vision = bool(model_specs.get("supports_vision", False))
+        # Web tool mode: whether the provider's hosted (server-side) web_search
+        # tool is requested and whether the client-side web_search/web_fetch
+        # tools are registered. Resolved from config.web_search_mode plus the
+        # model's supports_hosted_web_search catalog flag; the ToolCollection
+        # gate reads client_web_tools_enabled, the stream call reads
+        # hosted_web_search_active.
+        self.supports_hosted_web_search = bool(model_specs.get("supports_hosted_web_search", False))
+        self.web_search_mode = getattr(self.config, "web_search_mode", "auto") or "auto"
+        self._apply_web_search_state()
 
         self.llm = context.create_llm_client(agent_name=self.agent_name)
 
@@ -487,6 +504,15 @@ class BaseAgent(LogMixin):
         self._workflow_accounting: Optional["WorkflowRunAccounting"] = None
         self._accounting_reservation: Optional["AgentReservation"] = None
         self.total_tokens_used: int = 0
+        # Hosted web-search accounting side-channel. Searched/fetched content is
+        # injected into the model's context SERVER-side (restored on replay of
+        # web_search_call items, billed as input) and never reaches the client,
+        # so tiktoken-over-history can't see it. The residual — billed input
+        # minus the client-side count of the request actually sent — measures it
+        # and is added to the gauge in count_current_context. Updated by
+        # _update_hosted_search_residual; zeroed by compress_history.
+        self._hosted_injected_tokens: int = 0
+        self._last_raw_context_count: Optional[int] = None
         # Set by a blocking PostToolUse hook to end the turn after the current tool batch.
         self._hook_end_turn = False
         self.queued_input_provider: Optional[Callable[[], Awaitable[List[QueuedUserInput]]]] = None
@@ -652,6 +678,74 @@ class BaseAgent(LogMixin):
         if callable(initialize):
             initialize()
 
+    def _apply_web_search_state(self) -> None:
+        """Resolve web_search_mode + model capability into the two live gates.
+
+        ``hosted_web_search_active`` — request the provider's server-side
+        web_search tool on main-loop stream calls. ``client_web_tools_enabled``
+        — register the client-side web_search/web_fetch tools (read by the
+        ToolCollection gate). Hosted active always excludes the client tools:
+        two search paths confuse the model and waste schema tokens.
+        """
+        mode = (self.web_search_mode or "auto").lower()
+        supported = self.supports_hosted_web_search
+        if mode == "off":
+            hosted, client = False, False
+        elif mode == "client":
+            hosted, client = False, True
+        elif mode == "hosted":
+            if not supported:
+                provider = self.primary_model_config.provider
+                logger.warning(
+                    "web_search_mode=hosted, but %s/%s has no hosted web search; falling back to the client tools",
+                    getattr(provider, "value", provider),
+                    self.primary_model_config.model,
+                )
+            hosted, client = supported, not supported
+        else:  # auto
+            hosted, client = supported, not supported
+        self.hosted_web_search_active = hosted
+        self.client_web_tools_enabled = client
+
+    def apply_web_search_mode(self, mode: str) -> None:
+        """Change the web tool mode mid-session (TUI ``/web-search``).
+
+        Mirrors :meth:`apply_gigacode`: the tool registry rebuilds per call and
+        the next stream call reads the hosted gate, so no cache invalidation is
+        needed. No prompt work — the tools carry their own affordances.
+        """
+        self.web_search_mode = (mode or "auto").lower()
+        self._apply_web_search_state()
+
+    async def _emit_hosted_tool_call(self, delta: Dict[str, Any]) -> None:
+        """Render a completed hosted web_search call as a tool_call/tool_result pair.
+
+        The call executed on the provider's servers; there is no local tool
+        invocation and the searched content never reaches the client (it is
+        injected into the model's context server-side). The shared item id
+        correlates the pair in every transcript consumer.
+        """
+        block = WebSearchCallBlock(
+            item_id=delta.get("id") or None,
+            status=delta.get("status"),
+            action=delta.get("action") or {},
+        )
+        tool_call_id = block.item_id or str(uuid.uuid4())
+        await self.send_chat_message(
+            message_type="tool_call",
+            content=f"Calling {WebSearchCallBlock.TOOL_LABEL}: {block.label()}",
+            is_streaming=False,
+            tool_description=WebSearchCallBlock.TOOL_LABEL,
+            tool_call_id=tool_call_id,
+        )
+        await self.send_chat_message(
+            message_type="tool_result",
+            content=block.result_summary(),
+            is_streaming=False,
+            tool_description=WebSearchCallBlock.TOOL_LABEL,
+            tool_call_id=tool_call_id,
+        )
+
     def apply_goal(self, condition: Optional[str], prompt_extension: Optional["PromptExtension"] = None) -> None:
         """Set, replace, or clear the active autonomous goal for this session.
 
@@ -944,12 +1038,61 @@ class BaseAgent(LogMixin):
             model=self.primary_model_config.model,
             tools=self.tool_collection.get_tool_list(),
         )
+        # Hosted web-search content lives only in the server's copy of the
+        # context (restored on replay of the web_search_call items, billed as
+        # input) — the client history has nothing to count for it. Add the
+        # residual measured from billed usage so the gauge AND the compaction
+        # check both see the true context size. Nonzero only while un-compacted
+        # web_search_call blocks exist (see _update_hosted_search_residual).
+        self._last_raw_context_count = token_count.input_tokens
+        if self._hosted_injected_tokens > 0:
+            token_count.input_tokens += self._hosted_injected_tokens
 
         # Send context update event
         await self._send_context_update(token_count)
 
         return token_count
 
+    # Provisional residual bump per hosted web-search call, applied while the
+    # search-bearing response's own billing is telescoped (a response that
+    # searched is several internal invocations billed cumulatively, so its
+    # billed−counted residual overstates the persistent injected size). The next
+    # clean response replaces the estimate with the measured residual. Probe
+    # calibration 2026-08-04 (findings/probes/hosted_web_search_probe.py):
+    # one-call persistent overhead ≈850 (deepseek) / ≈5000 (openai) tokens —
+    # 6000 overestimates safely, and overestimating only compacts early.
+    HOSTED_SEARCH_PROVISIONAL_TOKENS = 6000
+
+    def _update_hosted_search_residual(self, assistant_message: Message) -> None:
+        """Track server-injected hosted-search content from billed usage.
+
+        Search-bearing responses bump the estimate by a provisional per-call
+        constant (their own billing telescopes internal rounds, so the direct
+        residual would overshoot and could trip compaction spuriously). Clean
+        responses — single invocation, so ``billed − counted`` is exact —
+        replace it with the measurement. No-ops for sessions that never
+        searched, keeping the known ±tokenizer-drift band out of the gauge.
+        """
+        content = assistant_message.content if isinstance(assistant_message.content, list) else []
+        new_calls = sum(1 for block in content if isinstance(block, WebSearchCallBlock))
+        if new_calls:
+            self._hosted_injected_tokens += self.HOSTED_SEARCH_PROVISIONAL_TOKENS * new_calls
+            return
+        if self._hosted_injected_tokens <= 0 and not self._history_contains_hosted_search():
+            return
+        billed = (assistant_message.usage_metadata or {}).get("prompt_tokens")
+        counted = self._last_raw_context_count
+        if not isinstance(billed, int) or counted is None:
+            return
+        self._hosted_injected_tokens = max(0, billed - counted)
+
+    def _history_contains_hosted_search(self) -> bool:
+        for message in self.history:
+            content = getattr(message, "content", None)
+            if isinstance(content, list) and any(isinstance(block, WebSearchCallBlock) for block in content):
+                return True
+        return False
+
     async def _send_context_update(self, token_count: TokenCount) -> None:
         """Send an event to update the UI about current context usage."""
         usage_percentage = (token_count.input_tokens / self.model_context_length) * 100
@@ -977,6 +1120,11 @@ class BaseAgent(LogMixin):
         show progress, then recounts + emits a context_update so the gauge
         refreshes. Returns the structured outcome.
         """
+        # Compacted-away web_search_call blocks stop being replayed, so the
+        # server stops restoring their content. Reset the hosted-search residual
+        # rather than carrying a stale figure; if search blocks survive in the
+        # verbatim tail, the next clean response re-measures it.
+        self._hosted_injected_tokens = 0
 
         async def on_info(message: str) -> None:
             await self.log_info(message, sender=self.agent_name)
@@ -2093,6 +2241,7 @@ class BaseAgent(LogMixin):
                             model=self.primary_model_config.model,
                             tools=self.tool_collection.get_tool_list(),
                             thinking=self.primary_model_config.thinking_effort,
+                            hosted_web_search=self.hosted_web_search_active,
                         ),
                     )
                 async with stream_cm as stream:
@@ -2135,8 +2284,46 @@ class BaseAgent(LogMixin):
 
                             await self.on_tool_use_start(event.tool_call_delta)
 
+                        elif event.type == "hosted_tool_call" and event.tool_call_delta:
+                            # A server-side web_search call completed on the
+                            # provider's infrastructure — no local execution.
+                            # Surface it as a normal tool_call/tool_result pair
+                            # so every transcript view renders it.
+                            #
+                            # Close the current thinking/response segment first
+                            # and rotate both uuids: transcript consumers key
+                            # streamed entries by uuid, so without rotation the
+                            # post-search reasoning folds into the bubble above
+                            # these rows instead of opening a new one below
+                            # them. Guards mirror the end-of-stream flushes: an
+                            # unopened thinking segment yields nothing, while
+                            # the response flush is unconditional (an empty
+                            # complete response chunk is a documented no-op for
+                            # every consumer) so a partially streamed response
+                            # entry is never stranded incomplete by rotation.
+                            if thinking_started or current_thinking:
+                                yield {
+                                    "type": "thinking",
+                                    "content": current_thinking,
+                                    "complete": True,
+                                    "uuid": thinking_uuid,
+                                }
+                                current_thinking = ""
+                                thinking_started = False
+                                thinking_uuid = str(uuid.uuid4())
+                            yield {
+                                "type": "response",
+                                "content": current_response,
+                                "complete": True,
+                                "uuid": response_uuid,
+                            }
+                            current_response = ""
+                            response_uuid = str(uuid.uuid4())
+                            await self._emit_hosted_tool_call(event.tool_call_delta)
+
                 assistant_message = await stream.get_final_message()
                 self._normalize_freeform_tool_calls(assistant_message)
+                self._update_hosted_search_residual(assistant_message)
                 assistant_message.usage_metadata["edit_protocol"] = self.edit_protocol.value
                 response_output_tokens = get_output_tokens(
                     assistant_message.usage_metadata,

{kolega_code-0.26.8 → kolega_code-0.26.10}/kolega_code/agent/conversation.py

@@ -22,6 +22,7 @@ from kolega_code.llm.models import (
     ThinkingBlock,
     ToolCall,
     ToolResult,
+    WebSearchCallBlock,
 )
 from kolega_code.llm.specs import prior_reasoning_is_replayable
 from kolega_code.utils import images as image_utils
@@ -336,7 +337,7 @@ def _adapt_content_blocks_for_provider(
             )
             adapted.append(adapted_block)
             changed = changed or image_changed
-        elif isinstance(block, (ThinkingBlock, RedactedThinkingBlock, ResponsesReasoningBlock)):
+        elif isinstance(block, (ThinkingBlock, RedactedThinkingBlock, ResponsesReasoningBlock, WebSearchCallBlock)):
             if _preserve_reasoning_block(
                 block,
                 source_provider=source_provider,

{kolega_code-0.26.8 → kolega_code-0.26.10}/kolega_code/agent/eval/kernel.py

@@ -414,20 +414,36 @@ class EvalKernelManager:
         thread_id: str,
         project_path: Path,
         config: object,
+        scratchpad_dir: Optional[Path] = None,
     ) -> "EvalKernelManager":
         """Shared manager for an agent session; sub-agents join the same one."""
         key = (workspace_id, thread_id)
         manager = cls._registry.get(key)
         if manager is None or manager._shutdown:
-            manager = cls(workspace_id=workspace_id, thread_id=thread_id, project_path=project_path, config=config)
+            manager = cls(
+                workspace_id=workspace_id,
+                thread_id=thread_id,
+                project_path=project_path,
+                config=config,
+                scratchpad_dir=scratchpad_dir,
+            )
             cls._registry[key] = manager
         return manager
 
-    def __init__(self, *, workspace_id: str, thread_id: str, project_path: Path, config: object) -> None:
+    def __init__(
+        self,
+        *,
+        workspace_id: str,
+        thread_id: str,
+        project_path: Path,
+        config: object,
+        scratchpad_dir: Optional[Path] = None,
+    ) -> None:
         self.workspace_id = workspace_id
         self.thread_id = thread_id
         self.project_path = Path(project_path)
         self.config = config
+        self.scratchpad_dir = Path(scratchpad_dir) if scratchpad_dir else None
         self.session_id = uuid.uuid4().hex
         self._kernels: Dict[str, BaseKernel] = {}
         self._locks: Dict[str, asyncio.Lock] = {}
@@ -437,6 +453,17 @@ class EvalKernelManager:
 
     # -- kernels ------------------------------------------------------------
 
+    def _kernel_child_env(self) -> Dict[str, str]:
+        """Base env for kernel subprocesses, shared by the py and js kernels.
+
+        KOLEGA_SCRATCHPAD matches the variable injected into terminal sessions,
+        so eval cells and shell commands share one durable session location.
+        """
+        env = build_child_env()
+        if self.scratchpad_dir is not None:
+            env["KOLEGA_SCRATCHPAD"] = str(self.scratchpad_dir)
+        return env
+
     def _env_manager_for_thread(self) -> EvalEnvironmentManager:
         if self._env_manager is None:
             env_path_raw = _cfg_str(self.config, "eval_env_path")
@@ -464,7 +491,7 @@ class EvalKernelManager:
 
         env_info = await self._ensure_env()
         bridge = await ToolBridge.ensure()
-        kernel_env = build_child_env()
+        kernel_env = self._kernel_child_env()
         kernel_env.update(
             {
                 "KOLEGA_TOOL_BRIDGE_URL": bridge.url,
@@ -502,7 +529,7 @@ class EvalKernelManager:
         package_json = js_home / "package.json"
         if not package_json.exists():
             package_json.write_text("{}\n", encoding="utf-8")
-        kernel_env = build_child_env()
+        kernel_env = self._kernel_child_env()
         npm_cmd = runtime.npm_install_cmd(js_home)
         kernel_env.update(
             {

{kolega_code-0.26.8 → kolega_code-0.26.10}/kolega_code/agent/prompt_templates/extensions/cli/scratchpad.md.j2

@@ -2,6 +2,8 @@ You have a private scratchpad working directory for this session at:
 
 `{{ scratchpad_path }}`
 
+This path is also exported as the environment variable `KOLEGA_SCRATCHPAD` in every shell command and eval kernel this session runs (login shells included), so in commands and scripts refer to it as `$KOLEGA_SCRATCHPAD` instead of re-declaring or retyping the literal path.
+
 Use it for throwaway work that must not touch the user's working tree: one-off scripts, ad-hoc virtual environments, downloaded files, extracted archives, generated intermediates, and log captures. This is the only location outside the working directory where you may create files without asking.
 
 Rules: