Kimi CLI

  659      async def run(
  660          self,
  661          user_input: str | list[ContentPart],
  662          *,
  663          skip_user_prompt_hook: bool = False,
  664      ):
  665          approval_source_token = None
  666          created_approval_source: ApprovalSource | None = None
  667          turn_started = False
  668          turn_finished = False
  669          interrupt_reason: str | None = None
  670          turn_t0 = time.monotonic()
  671          self._set_trace_id(None)
  672          if get_current_approval_source_or_none() is None:
  673              created_approval_source = ApprovalSource(kind="foreground_turn", id=uuid.uuid4().hex)
  674              approval_source_token = set_current_approval_source(created_approval_source)
  675          try:
  676              # Refresh OAuth tokens on each turn to avoid idle-time expirations.
  677              await self._runtime.oauth.ensure_fresh(self._runtime)
  678  
  679              # Set session_id ContextVar for toolset hooks
  680              from kimi_cli.soul.toolset import set_session_id
  681  
  682              set_session_id(self._runtime.session.id)
      … 50 lines omitted; exact range 659–742 …
  733                          await ret
  734              elif self._loop_control.max_ralph_iterations != 0:
  735                  runner = FlowRunner.ralph_loop(
  736                      user_message,
  737                      self._loop_control.max_ralph_iterations,
  738                  )
  739                  await runner.run(self, "")
  740              else:
  741                  await self._turn(user_message)
  742  

 1132          # ═══════════════════════════════════════════════════════════════════════
 1133          # 2e.1. NOTIFICATION DELIVERY (root role only)
 1134          # ═══════════════════════════════════════════════════════════════════════
 1135          if self.is_root:
 1136  
 1137              async def _append_notification(view: NotificationView) -> None:
 1138                  await self._context.append_message(build_notification_message(view, self._runtime))
 1139                  # --- Notification hook ---
 1140                  from kimi_cli.hooks import events
 1141  
 1142                  _hook_task = asyncio.create_task(
 1143                      self._hook_engine.trigger(
 1144                          "Notification",
 1145                          matcher_value=view.event.type,
 1146                          input_data=events.notification(
 1147                              session_id=self._runtime.session.id,
 1148                              cwd=str(Path.cwd()),
 1149                              sink="llm",
 1150                              notification_type=view.event.type,
 1151                              title=view.event.title,
 1152                              body=view.event.body,
 1153                              severity=view.event.severity,
 1154                          ),
 1155                      )
      … 29 lines omitted; exact range 1132–1194 …
 1185              system_prompt=self._agent.system_prompt,
 1186              tools=self._agent.toolset.tools,
 1187              history=effective_history,
 1188              input_tokens_floor=self._context.token_count_with_pending,
 1189          )
 1190          request_chat_provider = with_kimi_generation_overrides(chat_provider, generation_overrides)
 1191          request_chat_provider = with_trace_callback(
 1192              request_chat_provider,
 1193              self._set_trace_id,
 1194          )

  622      def steer(self, content: str | list[ContentPart]) -> None:
  623          """Queue a steer message for injection into the current turn."""
  624          self._steer_queue.put_nowait(content)
  625  
  626      async def _consume_pending_steers(self) -> bool:
  627          """Drain the steer queue and inject as follow-up user messages.
  628  
  629          Returns True if any steers were consumed.
  630  
  631          Note: /btw is intercepted at the UI layer (``classify_input``) before
  632          reaching the steer queue, so it never appears here.
  633          """
  634          consumed = False
  635          while not self._steer_queue.empty():
  636              content = self._steer_queue.get_nowait()
  637              await self._inject_steer(content)
  638              wire_send(SteerInput(user_input=content))
  639              consumed = True
  640          return consumed
  641  
  642      async def _inject_steer(self, content: str | list[ContentPart]) -> None:
  643          """Inject a single steer as a regular follow-up user message."""
  644          parts = cast(
  645              list[ContentPart],
  646              [TextPart(text=content)] if isinstance(content, str) else list(content),
  647          )
  648          message = Message(role="user", content=parts)
  649          if self._runtime.llm is None:
  650              raise LLMNotSet()
  651          if missing_caps := check_message(message, self._runtime.llm.capabilities):
  652              raise LLMNotSupported(self._runtime.llm, list(missing_caps))
  653          await self._context.append_message(message)

 1220          def _before_step_retry_sleep(retry_state: RetryCallState) -> None:
 1221              self._retry_log("step", retry_state)
 1222              self._emit_step_retry(retry_state, max_attempts=max_attempts)
 1223  
 1224          @tenacity.retry(
 1225              retry=retry_if_exception(self._is_retryable_error),
 1226              before_sleep=_before_step_retry_sleep,
 1227              wait=wait_exponential_jitter(initial=0.3, max=5, jitter=0.5),
 1228              stop=stop_after_attempt(max_attempts),
 1229              reraise=True,
 1230          )
 1231          async def _kosong_step_with_retry() -> StepResult:
 1232              return await self._run_with_connection_recovery(
 1233                  "step",
 1234                  _run_step_once,
 1235                  chat_provider=chat_provider,
 1236              )
 1237  
 1238          t0 = time.monotonic()
 1239          try:
 1240              result = await _kosong_step_with_retry()
 1241          except Exception as _step_exc:
 1242              if isinstance(_step_exc, ChatProviderError):
 1243                  _track_api_error(
 1244                      _step_exc,
 1245                      llm=self._runtime.llm,
 1246                      duration_ms=int((time.monotonic() - t0) * 1000),
 1247                      input_tokens=self._context.token_count,
 1248                  )
 1249              raise

   52      message = Message(role="assistant", content=[])
   53      pending_part: StreamedMessagePart | None = None  # message part that is currently incomplete
   54  
   55      logger.trace("Generating with history: {history}", history=history)
   56      stream = await chat_provider.generate(system_prompt, tools, history)
   57      if on_trace_id:
   58          # getattr for robustness against third-party StreamedMessage
   59          # implementations that predate the trace_id property.
   60          await callback(on_trace_id, getattr(stream, "trace_id", None))
   61      async for part in stream:
   62          logger.trace("Received part: {part}", part=part)
   63          if on_message_part:
   64              await callback(on_message_part, part.model_copy(deep=True))
   65  
   66          if pending_part is None:
   67              pending_part = part
   68          elif not pending_part.merge_in_place(part):  # try merge into the pending part
   69              # unmergeable part must push the pending part to the buffer
   70              _message_append(message, pending_part)
   71              if isinstance(pending_part, ToolCall) and on_tool_call:
   72                  await callback(on_tool_call, pending_part)
   73              pending_part = part
   74  
   75      # end of message
      … 18 lines omitted; exact range 52–103 …
   94              "stream was interrupted or the output token budget was exhausted "
   95              "during reasoning."
   96          )
   97  
   98      return GenerateResult(
   99          id=stream.id,
  100          message=message,
  101          usage=stream.usage,
  102          trace_id=getattr(stream, "trace_id", None),
  103      )

  326  def create_llm(
  327      provider: LLMProvider,
  328      model: LLMModel,
  329      *,
  330      thinking: bool | None = None,
  331      session_id: str | None = None,
  332      oauth: OAuthManager | None = None,
  333  ) -> LLM | None:
  334      if provider.type not in {"_echo", "_scripted_echo"} and (
  335          not provider.base_url or not model.model
  336      ):
  337          logger.warning(
  338              "Cannot create LLM: missing base_url or model (provider_type={provider_type})",
  339              provider_type=provider.type,
  340          )
  341          return None
  342  
  343      resolved_api_key = (
  344          oauth.resolve_api_key(provider.api_key, provider.oauth)
  345          if oauth and provider.oauth
  346          else provider.api_key.get_secret_value()
  347      )
  348  
  349      match provider.type:
      … 111 lines omitted; exact range 326–470 …
  461                      model=model.model,
  462                      base_url=provider.base_url,
  463                      api_key=resolved_api_key,
  464                      default_headers=_kimi_default_headers(provider, oauth),
  465                  ),
  466                  chaos_config=ChaosConfig(
  467                      error_probability=0.8,
  468                      error_types=[429, 500, 503],
  469                  ),
  470              )

  181  def compute_max_completion_tokens(
  182      *,
  183      max_context_size: int,
  184      input_tokens: int,
  185      response_budget: int | None,
  186      fallback_budget: int = DEFAULT_UNKNOWN_CONTEXT_COMPLETION_TOKENS,
  187  ) -> int:
  188      """Compute the Kimi completion cap from the hard cap and remaining context."""
  189      if max_context_size <= 0:
  190          return max(1, response_budget if response_budget is not None else fallback_budget)
  191  
  192      input_tokens = max(0, input_tokens)
  193      remaining = max(1, max_context_size - input_tokens)
  194      requested = response_budget if response_budget is not None else max_context_size
  195      return max(1, min(requested, remaining))
  196  
  197  
  198  def estimate_request_tokens(
  199      system_prompt: str,
  200      tools: Sequence[Tool],
  201      history: Sequence[Message],
  202  ) -> int:
  203      """Estimate all token-bearing parts of a chat request.
  204  
      … 49 lines omitted; exact range 181–263 …
  254  
  255      for tool_call in message.tool_calls or ():
  256          total += _estimate_text_tokens(tool_call.id)
  257          total += _estimate_text_tokens(tool_call.function.name)
  258          total += _estimate_text_tokens(tool_call.function.arguments or "")
  259          if tool_call.extras:
  260              total += _estimate_text_tokens(
  261                  json.dumps(tool_call.extras, ensure_ascii=False, separators=(",", ":"))
  262              )
  263      return total

   20  class Context:
   21      def __init__(self, file_backend: Path):
   22          self._file_backend = file_backend
   23          self._history: list[Message] = []
   24          self._token_count: int = 0
   25          self._pending_token_estimate: int = 0
   26          self._next_checkpoint_id: int = 0
   27          """The ID of the next checkpoint, starting from 0, incremented after each checkpoint."""
   28          self._system_prompt: str | None = None
   29  
   30      async def restore(self) -> bool:
   31          logger.debug("Restoring context from file: {file_backend}", file_backend=self._file_backend)
   32          if self._history:
   33              logger.error("The context storage is already modified")
   34              raise RuntimeError("The context storage is already modified")
   35          if not self._file_backend.exists():
   36              logger.debug("No context file found, skipping restoration")
   37              return False
   38          if self._file_backend.stat().st_size == 0:
   39              logger.debug("Empty context file, skipping restoration")
   40              return False
   41  
   42          messages_after_last_usage: list[Message] = []
   43          async with aiofiles.open(self._file_backend, encoding="utf-8", errors="replace") as f:
      … 12 lines omitted; exact range 20–65 …
   56                  self._apply_context_record(
   57                      line_json,
   58                      history=self._history,
   59                      messages_after_last_usage=messages_after_last_usage,
   60                      file_backend=self._file_backend,
   61                      line_no=line_no,
   62                  )
   63  
   64          self._pending_token_estimate = estimate_text_tokens(messages_after_last_usage)
   65          return True

  123      async def checkpoint(self, add_user_message: bool):
  124          checkpoint_id = self._next_checkpoint_id
  125          self._next_checkpoint_id += 1
  126          logger.debug("Checkpointing, ID: {id}", id=checkpoint_id)
  127  
  128          async with aiofiles.open(self._file_backend, "a", encoding="utf-8") as f:
  129              await f.write(json.dumps({"role": "_checkpoint", "id": checkpoint_id}) + "\n")
  130          if add_user_message:
  131              await self.append_message(
  132                  Message(role="user", content=[system(f"CHECKPOINT {checkpoint_id}")])
  133              )
  134  
  135      async def revert_to(self, checkpoint_id: int):
  136          """
  137          Revert the context to the specified checkpoint.
  138          After this, the specified checkpoint and all subsequent content will be
  139          removed from the context. File backend will be rotated.
  140  
  141          Args:
  142              checkpoint_id (int): The ID of the checkpoint to revert to. 0 is the first checkpoint.
  143  
  144          Raises:
  145              ValueError: When the checkpoint does not exist.
  146              RuntimeError: When no available rotation path is found.
      … 44 lines omitted; exact range 123–200 …
  191                      line_json,
  192                      history=self._history,
  193                      messages_after_last_usage=messages_after_last_usage,
  194                      file_backend=rotated_file_path,
  195                      line_no=line_no,
  196                  )
  197                  if keep_line:
  198                      await new_file.write(line)
  199  
  200          self._pending_token_estimate = estimate_text_tokens(messages_after_last_usage)

   37          The estimate is intentionally conservative — it will be replaced by the
   38          real value on the next LLM call.
   39          """
   40          if self.usage is not None and len(self.messages) > 0:
   41              summary_tokens = self.usage.output
   42              preserved_tokens = estimate_text_tokens(self.messages[1:])
   43              return summary_tokens + preserved_tokens
   44  
   45          return estimate_text_tokens(self.messages)
   46  
   47  
   48  def estimate_text_tokens(messages: Sequence[Message]) -> int:
   49      """Estimate tokens from message text content using a character-based heuristic."""
   50      total_chars = 0
   51      for msg in messages:
   52          for part in msg.content:
   53              if isinstance(part, TextPart):
   54                  total_chars += len(part.text)
   55      # ~4 chars per token for English; somewhat underestimates for CJK text,
   56      # but this is a temporary estimate that gets corrected on the next LLM call.
   57      return total_chars // 4
   58  
   59  
   60  def should_auto_compact(
      … 12 lines omitted; exact range 37–82 …
   73      return (
   74          token_count >= max_context_size * trigger_ratio
   75          or token_count + reserved_context_size >= max_context_size
   76      )
   77  
   78  
   79  @runtime_checkable
   80  class Compaction(Protocol):
   81      async def compact(
   82          self,

 1432          chat_provider = self._runtime.llm.chat_provider if self._runtime.llm is not None else None
 1433          compaction_overrides = None
 1434          if chat_provider is not None and isinstance(self._compaction, SimpleCompaction):
 1435              compact_message, to_preserve = self._compaction.prepare(
 1436                  self._context.history,
 1437                  custom_instruction=custom_instruction,
 1438              )
 1439              if compact_message is not None:
 1440                  post_compaction_history = [
 1441                      Message(
 1442                          role="user",
 1443                          content=[system(COMPACTION_OUTPUT_PREFIX)],
 1444                      ),
 1445                      *to_preserve,
 1446                  ]
 1447                  if self.is_root:
 1448                      active_task_snapshot = build_active_task_snapshot(
 1449                          self._runtime.background_tasks
 1450                      )
 1451                      if active_task_snapshot is not None:
 1452                          post_compaction_history.append(
 1453                              Message(
 1454                                  role="user",
 1455                                  content=[
      … 11 lines omitted; exact range 1432–1476 …
 1467                      self._agent.toolset.tools,
 1468                      post_compaction_history,
 1469                  )
 1470                  compaction_overrides = self._compute_completion_overrides(
 1471                      chat_provider,
 1472                      system_prompt=COMPACTION_SYSTEM_PROMPT,
 1473                      tools=(),
 1474                      history=[compact_message],
 1475                      input_tokens_floor=post_compaction_input_tokens,
 1476                  )

  411      # Register built-in subagent types before loading tools because some tools render
  412      # descriptions from the labor market on initialization.
  413      for subagent_name, subagent_spec in agent_spec.subagents.items():
  414          logger.debug(
  415              "Registering builtin subagent type: {subagent_name}", subagent_name=subagent_name
  416          )
  417          builtin_spec = load_agent_spec(subagent_spec.path)
  418          tool_policy = (
  419              ToolPolicy(mode="allowlist", tools=tuple(builtin_spec.allowed_tools))
  420              if builtin_spec.allowed_tools is not None
  421              else ToolPolicy(mode="inherit")
  422          )
  423          runtime.labor_market.add_builtin_type(
  424              AgentTypeDefinition(
  425                  name=subagent_name,
  426                  description=subagent_spec.description,
  427                  agent_file=subagent_spec.path,
  428                  when_to_use=builtin_spec.when_to_use,
  429                  default_model=builtin_spec.model,
  430                  tool_policy=tool_policy,
  431              )
  432          )
  433  
  434      toolset = KimiToolset()
      … 7 lines omitted; exact range 411–451 …
  442          DenwaRenji: runtime.denwa_renji,
  443          Approval: runtime.approval,
  444          LaborMarket: runtime.labor_market,
  445          Environment: runtime.environment,
  446      }
  447      tools = agent_spec.allowed_tools if agent_spec.allowed_tools is not None else agent_spec.tools
  448      if agent_spec.exclude_tools:
  449          logger.debug("Excluding tools: {tools}", tools=agent_spec.exclude_tools)
  450          tools = [tool for tool in tools if tool not in agent_spec.exclude_tools]
  451      toolset.load_tools(tools, tool_deps)

  134      tool_calls: list[ToolCall] = []
  135      tool_result_futures: dict[str, ToolResultFuture] = {}
  136  
  137      def future_done_callback(future: ToolResultFuture):
  138          if on_tool_result:
  139              try:
  140                  result = future.result()
  141                  on_tool_result(result)
  142              except asyncio.CancelledError:
  143                  return
  144  
  145      async def on_tool_call(tool_call: ToolCall):
  146          tool_calls.append(tool_call)
  147          result = toolset.handle(tool_call)
  148  
  149          if isinstance(result, ToolResult):
  150              future = ToolResultFuture()
  151              future.add_done_callback(future_done_callback)
  152              future.set_result(result)
  153              tool_result_futures[tool_call.id] = future
  154          else:
  155              result.add_done_callback(future_done_callback)
  156              tool_result_futures[tool_call.id] = result
  157  
  158      try:
  159          result = await generate(
  160              chat_provider,
  161              system_prompt,
  162              toolset.tools,
  163              history,
  164              on_message_part=on_message_part,
  165              on_tool_call=on_tool_call,
  166              on_trace_id=on_trace_id,
  167          )

  116  _REMINDER_TEXT_1 = (
  117      "\n\n<system-reminder>\n"
  118      "You are repeating the exact same tool call with identical parameters."
  119      " Please carefully analyze the previous result. If the task is not yet complete,"
  120      " try a different method or parameters instead of repeating the same call."
  121      "\n</system-reminder>"
  122  )
  123  
  124  
  125  def _make_reminder_text_2(tool_name: str, repeat_count: int, canonical_args: str) -> str:
  126      return (
  127          "\n\n<system-reminder>\n"
  128          "You have repeatedly called the same tool with identical parameters many times.\n"
  129          "Repeated tool call detected:\n"
  130          f"- tool: {tool_name}\n"
  131          f"- repeated_times: {repeat_count}\n"
  132          f"- arguments: {canonical_args}\n"
  133          "The previous repeated calls did not make progress. Do not call this exact same tool "
  134          "with the exact same arguments again.\n"
  135          "Carefully inspect the latest tool result and choose a different next action, "
  136          "different parameters, or finish the task if enough evidence has been gathered."
  137          "\n</system-reminder>"
  138      )
  139  
      … 23 lines omitted; exact range 116–172 …
  163  ) -> tuple[RepeatAction, str | None]:
  164      if streak >= _REPEAT_FORCE_STOP_STREAK:
  165          return "stop", _REMINDER_TEXT_3
  166      if streak >= _REPEAT_REMINDER_3_START:
  167          return "r3", _REMINDER_TEXT_3
  168      if streak >= _REPEAT_REMINDER_2_START:
  169          return "r2", _make_reminder_text_2(tool_name, streak, canonical_args)
  170      if streak >= _REPEAT_REMINDER_1_START:
  171          return "r1", _REMINDER_TEXT_1
  172      return "none", None

   22  MAX_FOREGROUND_TIMEOUT = 5 * 60
   23  MAX_BACKGROUND_TIMEOUT = 24 * 60 * 60
   24  
   25  
   26  class Params(BaseModel):
   27      command: str = Field(description="The command to execute.")
   28      timeout: int = Field(
   29          description=(
   30              "The timeout in seconds for the command to execute. "
   31              "If the command takes longer than this, it will be killed."
   32          ),
   33          default=60,
   34          ge=1,
   35          le=MAX_BACKGROUND_TIMEOUT,
   36      )
   37      run_in_background: bool = Field(
   38          default=False,
   39          description="Whether to run the command as a background task.",
   40      )
   41      description: str = Field(
   42          default="",
   43          description=(
   44              "A short description for the background task. Required when run_in_background=true."
   45          ),
      … 2 lines omitted; exact range 22–57 …
   48      @model_validator(mode="after")
   49      def _validate_background_fields(self) -> Self:
   50          if self.run_in_background and not self.description.strip():
   51              raise ValueError("description is required when run_in_background is true")
   52          if not self.run_in_background and self.timeout > MAX_FOREGROUND_TIMEOUT:
   53              raise ValueError(
   54                  f"timeout must be <= {MAX_FOREGROUND_TIMEOUT}s for foreground commands; "
   55                  f"use run_in_background=true for longer timeouts (up to {MAX_BACKGROUND_TIMEOUT}s)"
   56              )
   57          return self

  130  class Approval:
  131      def __init__(
  132          self,
  133          yolo: bool = False,
  134          *,
  135          state: ApprovalState | None = None,
  136          runtime: ApprovalRuntime | None = None,
  137      ):
  138          self._state = state or ApprovalState(yolo=yolo)
  139          self._runtime = runtime or ApprovalRuntime()
  140  
  141      def share(self) -> Approval:
  142          """Create a new approval queue that shares approval state."""
  143          return Approval(state=self._state, runtime=self._runtime)
  144  
  145      def set_runtime(self, runtime: ApprovalRuntime) -> None:
  146          self._runtime = runtime
  147  
  148      @property
  149      def runtime(self) -> ApprovalRuntime:
  150          return self._runtime
  151  
  152      def set_yolo(self, yolo: bool) -> None:
  153          self._state.yolo = yolo
      … 36 lines omitted; exact range 130–199 …
  190          return self._state.afk or self._state.runtime_afk
  191  
  192      def is_afk_flag(self) -> bool:
  193          """True only when persisted afk mode is active."""
  194          return self._state.afk
  195  
  196      def is_runtime_afk(self) -> bool:
  197          """True only when afk came from this invocation."""
  198          return self._state.runtime_afk
  199  

  409      def _bind_plan_mode_tools(self) -> None:
  410          """Bind plan mode state to tools that support it."""
  411          if not isinstance(self._agent.toolset, KimiToolset):
  412              return
  413  
  414          def checker() -> bool:
  415              return self._plan_mode
  416  
  417          def path_getter() -> Path | None:
  418              return self.get_plan_file_path()
  419  
  420          # WriteFile gets both checker and path_getter (for plan file auto-approve)
  421          from kimi_cli.tools.file.write import WriteFile
  422  
  423          write_tool = self._agent.toolset.find("WriteFile")
  424          if isinstance(write_tool, WriteFile):
  425              write_tool.bind_plan_mode(checker, path_getter)
  426  
  427          from kimi_cli.tools.file.replace import StrReplaceFile
  428  
  429          replace_tool = self._agent.toolset.find("StrReplaceFile")
  430          if isinstance(replace_tool, StrReplaceFile):
  431              replace_tool.bind_plan_mode(checker, path_getter)
  432  
      … 21 lines omitted; exact range 409–463 …
  454                  self._approval.is_auto_approve,
  455              )
  456  
  457          # AskUserQuestion — bind afk checker for auto-dismiss.
  458          # Yolo alone keeps the tool live; only afk (no user present) dismisses.
  459          from kimi_cli.tools.ask_user import AskUserQuestion
  460  
  461          ask_tool = self._agent.toolset.find("AskUserQuestion")
  462          if isinstance(ask_tool, AskUserQuestion):
  463              ask_tool.bind_afk(self._approval.is_afk)

   67  # Working Environment
   68  
   69  ## Operating System
   70  
   71  You are running on **${KIMI_OS}**. The Shell tool executes commands using **${KIMI_SHELL}**.{% if KIMI_OS == "Windows" %} Use Unix shell syntax inside Shell commands — `/dev/null` not `NUL`, forward slashes in paths (backslashes are escape characters in bash).{% endif +%}
   72  
   73  The operating environment is not in a sandbox. Any actions you do will immediately affect the user's system. So you MUST be extremely cautious. Unless being explicitly instructed to do so, you should never access (read/write/execute) files outside of the working directory.
   74  
   75  ## Date and Time
   76  
   77  The current date and time in ISO format is `${KIMI_NOW}`. This is only a reference for you when searching the web, or checking file modification time, etc. If you need the exact time, use Shell tool with proper command.
   78  
   79  ## Working Directory
   80  
   81  The current working directory is `${KIMI_WORK_DIR}`. This should be considered as the project root if you are instructed to perform tasks on the project. Every file system operation will be relative to the working directory if you do not explicitly specify the absolute path. Tools may require absolute paths for some parameters, IF SO, YOU MUST use absolute paths for these parameters.

   65  class HookEngine:
   66      """Loads hook definitions and executes matching hooks in parallel.
   67  
   68      Supports two hook sources:
   69      - Server-side (config.toml): shell commands executed locally
   70      - Client-side (wire subscriptions): forwarded to client via HookRequest
   71      """
   72  
   73      def __init__(
   74          self,
   75          hooks: list[HookDef] | None = None,
   76          cwd: str | None = None,
   77          *,
   78          on_triggered: OnTriggered | None = None,
   79          on_resolved: OnResolved | None = None,
   80          on_wire_hook: OnWireHookRequest | None = None,
   81      ):
   82          self._hooks: list[HookDef] = list(hooks) if hooks else []
   83          self._wire_subs: list[WireHookSubscription] = []
   84          self._cwd = cwd
   85          self._on_triggered = on_triggered
   86          self._on_resolved = on_resolved
   87          self._on_wire_hook = on_wire_hook
   88          self._by_event: dict[str, list[HookDef]] = {}
   89          self._wire_by_event: dict[str, list[WireHookSubscription]] = {}
   90          self._pending_fire_and_forget: set[asyncio.Task[Any]] = set()
   91          self._rebuild_index()

   37  class PluginTool(CallableTool):
   38      """A tool that executes a plugin command in a subprocess.
   39  
   40      Parameters are passed via stdin as JSON.
   41      stdout is captured as the tool result.
   42      Host credentials are injected as environment variables at runtime
   43      (not baked into config files) to handle OAuth token refresh.
   44      """
   45  
   46      def __init__(
   47          self,
   48          tool_spec: PluginToolSpec,
   49          plugin_dir: Path,
   50          *,
   51          inject: dict[str, str],
   52          config: Config,
   53          approval: Approval | None = None,
   54          **kwargs: Any,
   55      ):
   56          super().__init__(
   57              name=tool_spec.name,
   58              description=tool_spec.description,
   59              parameters=tool_spec.parameters or {"type": "object", "properties": {}},
   60              **kwargs,
      … 60 lines omitted; exact range 37–130 …
  121              error_msg = err_output or output or f"Exit code {proc.returncode}"
  122              return ToolError(
  123                  message=f"Plugin tool '{self.name}' failed: {error_msg}",
  124                  brief=f"Exit {proc.returncode}",
  125              )
  126  
  127          if err_output:
  128              logger.debug("Plugin tool {name} stderr: {err}", name=self.name, err=err_output)
  129  
  130          return ToolOk(output=output)

  467      if mcp_configs:
  468          validated_mcp_configs: list[MCPConfig] = []
  469          if mcp_configs:
  470              from fastmcp.mcp_config import MCPConfig
  471  
  472              for mcp_config in mcp_configs:
  473                  try:
  474                      validated_mcp_configs.append(
  475                          mcp_config
  476                          if isinstance(mcp_config, MCPConfig)
  477                          else MCPConfig.model_validate(mcp_config)
  478                      )
  479                  except pydantic.ValidationError as e:
  480                      raise MCPConfigError(f"Invalid MCP config: {e}") from e
  481          if start_mcp_loading:
  482              await toolset.load_mcp_tools(validated_mcp_configs, runtime, in_background=True)
  483          else:
  484              toolset.defer_mcp_tool_loading(validated_mcp_configs, runtime)
  485  

  494  def _load_system_prompt(
  495      path: Path, args: dict[str, str], builtin_args: BuiltinSystemPromptArgs
  496  ) -> str:
  497      logger.info("Loading system prompt: {path}", path=path)
  498      system_prompt = path.read_text(encoding="utf-8").strip()
  499      logger.debug(
  500          "Substituting system prompt with builtin args: {builtin_args}, spec args: {spec_args}",
  501          builtin_args=builtin_args,
  502          spec_args=args,
  503      )
  504      env = JinjaEnvironment(
  505          loader=FileSystemLoader(path.parent),
  506          keep_trailing_newline=True,
  507          lstrip_blocks=True,
  508          trim_blocks=True,
  509          variable_start_string="${",
  510          variable_end_string="}",
  511          undefined=StrictUndefined,
  512      )
  513      try:
  514          template = env.from_string(system_prompt)
  515          return template.render(asdict(builtin_args), **args)
  516      except UndefinedError as exc:
  517          raise SystemPromptTemplateError(f"Missing system prompt arg in {path}: {exc}") from exc

   87  async def load_agents_md(work_dir: KaosPath) -> str | None:
   88      """Discover and merge ``AGENTS.md`` files from the project root down to *work_dir*.
   89  
   90      For each directory on the path, the following candidates are checked in order:
   91  
   92      1. ``.kimi/AGENTS.md``  — project-local kimi config (highest priority)
   93      2. ``AGENTS.md``        — standard location
   94      3. ``agents.md``        — lowercase variant (mutually exclusive with 2)
   95  
   96      Within a single directory, ``.kimi/AGENTS.md`` and ``AGENTS.md``/``agents.md``
   97      are **both** loaded (with ``.kimi/`` first), but ``AGENTS.md`` and ``agents.md``
   98      are mutually exclusive (uppercase wins).
   99  
  100      All discovered files are concatenated root→leaf, separated by ``\\n\\n``, with
  101      source annotations.  Total size is capped at :data:`_AGENTS_MD_MAX_BYTES`.
  102      Budget is allocated leaf-first so deeper (more specific) files are never
  103      truncated in favour of shallower ones.
  104      """
  105      project_root = await find_project_root(work_dir)
  106      dirs = await _dirs_root_to_leaf(work_dir, project_root)
  107  
  108      # Phase 1: collect all candidate files (root → leaf order)
  109      discovered: list[tuple[KaosPath, str]] = []  # (path, content)
  110      for d in dirs:
      … 48 lines omitted; exact range 87–168 …
  159          remaining -= len(content.encode())
  160          budgeted[i] = (path, content)
  161  
  162      # Phase 3: assemble in root → leaf order, skipping entries emptied by truncation
  163      parts: list[str] = []
  164      for path, content in budgeted:
  165          if content:
  166              parts.append(f"<!-- From: {path} -->\n{content}")
  167  
  168      return "\n\n".join(parts) if parts else None

  242      merge_all_available_skills: bool = Field(
  243          default=True,
  244          description=(
  245              "Merge skills from all existing brand directories (kimi/claude/codex) "
  246              "instead of using only the first one found. Defaults to true so users "
  247              "who keep skills in multiple brand directories see everything out of "
  248              "the box; set to false to restore the first-match-only behaviour."
  249          ),
  250      )
  251      extra_skill_dirs: list[str] = Field(
  252          default_factory=list,
  253          description=(
  254              "Extra directories to discover skills from, added on top of the "
  255              "built-in / user / project locations. Each entry may be an absolute "
  256              "path, ``~``-prefixed (expanded against $HOME), or relative to the "
  257              "project root (the nearest ``.git`` directory above the work dir). "
  258              "Missing paths are silently skipped."
  259          ),

  411      # Register built-in subagent types before loading tools because some tools render
  412      # descriptions from the labor market on initialization.
  413      for subagent_name, subagent_spec in agent_spec.subagents.items():
  414          logger.debug(
  415              "Registering builtin subagent type: {subagent_name}", subagent_name=subagent_name
  416          )
  417          builtin_spec = load_agent_spec(subagent_spec.path)
  418          tool_policy = (
  419              ToolPolicy(mode="allowlist", tools=tuple(builtin_spec.allowed_tools))
  420              if builtin_spec.allowed_tools is not None
  421              else ToolPolicy(mode="inherit")
  422          )
  423          runtime.labor_market.add_builtin_type(
  424              AgentTypeDefinition(
  425                  name=subagent_name,
  426                  description=subagent_spec.description,
  427                  agent_file=subagent_spec.path,
  428                  when_to_use=builtin_spec.when_to_use,
  429                  default_model=builtin_spec.model,
  430                  tool_policy=tool_policy,
  431              )

   17  MAX_FOREGROUND_TIMEOUT = 60 * 60  # 1 hour
   18  MAX_BACKGROUND_TIMEOUT = 60 * 60  # 1 hour
   19  
   20  
   21  class Params(BaseModel):
   22      description: str = Field(description="A short (3-5 word) description of the task")
   23      prompt: str = Field(description="The task for the agent to perform")
   24      subagent_type: str = Field(
   25          default="coder",
   26          description="The built-in agent type to use. Defaults to `coder`.",
   27      )
   28      model: str | None = Field(
   29          default=None,
   30          description=(
   31              "Optional model override. Selection priority is: this parameter, then the built-in "
   32              "type default model, then the parent agent's current model."
   33          ),
   34      )
   35      resume: str | None = Field(
   36          default=None,
   37          description="Optional agent ID to resume instead of creating a new instance.",
   38      )
   39      run_in_background: bool = Field(
   40          default=False,
      … 10 lines omitted; exact range 17–60 …
   51              "Foreground: no default timeout (runs until completion), max 3600s (1hr). "
   52              "Background: default from config (15min), max 3600s (1hr). "
   53              "The agent is stopped if it exceeds this limit."
   54          ),
   55          ge=30,
   56          le=MAX_BACKGROUND_TIMEOUT,
   57      )
   58  
   59      @property
   60      def effective_timeout(self) -> int | None:

  339      def copy_for_subagent(
  340          self,
  341          *,
  342          agent_id: str,
  343          subagent_type: str,
  344          llm_override: LLM | None = None,
  345      ) -> Runtime:
  346          """Clone runtime for a subagent."""
  347          return Runtime(
  348              config=self.config,
  349              oauth=self.oauth,
  350              llm=llm_override if llm_override is not None else self.llm,
  351              session=self.session,
  352              builtin_args=self.builtin_args,
  353              denwa_renji=DenwaRenji(),  # subagent must have its own DenwaRenji
  354              approval=self.approval.share(),
  355              labor_market=self.labor_market,
  356              environment=self.environment,
  357              notifications=self.notifications,
  358              background_tasks=self.background_tasks.copy_for_role("subagent"),
  359              skills=self.skills,
  360              # Share the same list reference so /add-dir mutations propagate to all agents
  361              additional_dirs=self.additional_dirs,
  362              skills_dirs=self.skills_dirs,
  363              subagent_store=self.subagent_store,
  364              approval_runtime=self.approval_runtime,
  365              root_wire_hub=self.root_wire_hub,
  366              subagent_id=agent_id,
  367              subagent_type=subagent_type,
  368              role="subagent",
  369          )

 1009              # ── 2b. Step Begin ──────────────────────────────────────────────────
 1010              wire_send(StepBegin(n=step_no))
 1011              back_to_the_future: BackToTheFuture | None = None
 1012              step_outcome: StepOutcome | None = None
 1013  
 1014              try:
 1015                  # ── 2c. Context Compaction ──────────────────────────────────────
 1016                  if should_auto_compact(
 1017                      self._context.token_count_with_pending,
 1018                      self._runtime.llm.max_context_size,
 1019                      trigger_ratio=self._loop_control.compaction_trigger_ratio,
 1020                      reserved_context_size=self._loop_control.reserved_context_size,
 1021                  ):
 1022                      logger.info("Context too long, compacting...")
 1023                      try:
 1024                          await self.compact_context()
 1025                      except Exception as compact_err:
 1026                          logger.error(
 1027                              "Context compaction failed at step {step_no}: {error_type}: {error}",
 1028                              step_no=step_no,
 1029                              error_type=type(compact_err).__name__,
 1030                              error=compact_err,
 1031                          )
 1032                          raise
      … 34 lines omitted; exact range 1009–1076 …
 1067                              session_id=self._runtime.session.id,
 1068                              cwd=str(Path.cwd()),
 1069                              error_type=type(e).__name__,
 1070                              error_message=str(e),
 1071                          ),
 1072                      )
 1073                  )
 1074                  _hook_task.add_done_callback(lambda t: t.exception() if not t.cancelled() else None)
 1075                  # break the agent loop
 1076                  raise

  261      telemetry: bool = Field(
  262          default=True,
  263          description="Enable anonymous telemetry to help improve kimi-cli. Set to false to disable.",
  264      )

   84      def save_state(self) -> None:
   85          """Persist the session state to disk.
   86  
   87          Reloads externally-mutable fields (title, archive) from disk first
   88          to avoid overwriting concurrent changes made by the web API.
   89          """
   90          fresh = load_session_state(self.dir)
   91          self.state.custom_title = fresh.custom_title
   92          self.state.title_generated = fresh.title_generated
   93          self.state.title_generate_attempts = fresh.title_generate_attempts
   94          self.state.archived = fresh.archived
   95          self.state.archived_at = fresh.archived_at
   96          self.state.auto_archive_exempt = fresh.auto_archive_exempt
   97          save_session_state(self.state, self.dir)