iosm-cli 0.2.7 → 0.2.8

package/docs/cli-reference.md

@@ -257,7 +257,7 @@ iosm --api-key sk-test-123           # Override for this run
 
 ### Available Tools
 
-`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `rg`, `fd`, `ast_grep`, `comby`, `jq`, `yq`, `semgrep`, `sed`, `semantic_search`, `fetch`, `git_read`, `fs_ops`
+`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `rg`, `fd`, `ast_grep`, `comby`, `jq`, `yq`, `semgrep`, `sed`, `semantic_search`, `fetch`, `web_search`, `git_read`, `git_write`, `fs_ops`, `todo_read`, `todo_write`
 
 Tool notes:
 - `rg`, `fd` are managed by iosm-cli and auto-resolved when missing.
@@ -265,8 +265,23 @@ Tool notes:
 - `sed` tool is preview/extraction-oriented; in-place edits are intentionally blocked.
 - `semantic_search` uses configured embeddings provider/index (`/semantic setup`).
 - `fetch` is profile-aware: read-only profiles allow only `GET/HEAD/OPTIONS`; write-capable profiles allow full HTTP method set.
-- `git_read` provides structured read-only git actions (`status`, `diff`, `log`, `blame`) without raw shell passthrough.
+- `fetch` can be used for remote GitHub inspection without cloning via GitHub API/RAW endpoints (for example `api.github.com`, `raw.githubusercontent.com`).
+- `web_search` is discovery-oriented (Tavily primary, fallback chain configurable via settings/environment). Use `fetch` to read specific URLs.
+- `git_read` provides structured read-only git actions (`status`, `diff`, `log`, `blame`, `show`, `branch_list`, `remote_list`, `rev_parse`) without raw shell passthrough.
+- `git_write` provides structured git write actions (`add`, `restore`, `reset_index`, `commit`, `switch`, `branch_create`, `fetch`, `pull`, `push`, `stash_*`) with action-specific validation and no raw passthrough. Network actions require enabling GitHub tools network access in settings.
 - `fs_ops` performs structured filesystem mutations (`mkdir`, `move`, `copy`, `delete`) with explicit `recursive`/`force` safety flags.
+- `todo_read` / `todo_write` provide persistent task-state tracking for multi-step work in the current workspace.
+
+Best-practice patterns:
+- Git analysis: `git_read status` -> targeted `git_read diff/log/blame/show` on the exact files/refs you need.
+- Git mutation: perform minimal-scope `git_write` actions first (explicit files/branch/message), then re-check with `git_read status/diff`.
+- Web research: use `web_search` for discovery (prefer `include_domains`, `exclude_domains`, `days`, `topic` for tighter scope), then validate claims with `fetch` on primary URLs.
+- For API endpoints via `fetch`, prefer `response_format=json`; for HTML/text pages use `response_format=text` (or `auto`) and tune `max_bytes`/`timeout` to keep output usable.
+- File exploration: use bounded reads/searches (`path`, `glob`, `context`, `limit`); for large files, page with `read` using `offset`/`limit` instead of dumping whole files.
+- File mutation: prefer `edit` for surgical changes and `write` for full rewrites; use `fs_ops` for `mkdir/move/copy/delete`, with `force=true` only when replacement/no-op behavior is intentional.
+- Structured data transforms: use `jq`/`yq` to compute/preview transforms, then persist the final state through `edit`/`write`.
+- Semantic retrieval: use `semantic_search status` first when relevance looks stale, then run `query`; run `index`/`rebuild` when config or index freshness requires it.
+- Multi-step execution: keep task progress synchronized with `todo_write` and recover state with `todo_read` before resuming long threads.
 
 **Examples:**
 

package/docs/configuration.md

@@ -78,12 +78,19 @@ Settings are merged in this order (later wins):
     "shell": "/bin/zsh",
     "cols": 120
   },
+  "githubTools": {
+    "networkEnabled": false,
+    "token": "optional-gh-token"
+  },
   "permissions": {
     "autoApprove": false
   }
 }
 ```
 
+`githubTools.networkEnabled` controls whether `git_write` network actions (`fetch`, `pull`, `push`) are allowed.  
+`githubTools.token` is optional and, when set, is injected for GitHub HTTPS authentication during network git actions.
+
 ## MCP Configuration
 
 Manage MCP servers from CLI and interactive mode:
@@ -218,6 +225,8 @@ The table below lists common environment variables, but is not exhaustive.
 | `IOSM_SHARE_VIEWER_URL` | Default | Custom base URL for `/share` links |
 | `IOSM_AI_ANTIGRAVITY_VERSION` | Auto | Override Antigravity user-agent version |
 | `IOSM_SKIP_VERSION_CHECK` | `false` | Disable update/version checks |
+| `TAVILY_API_KEY` | unset | Enables Tavily primary provider for `web_search` |
+| `IOSM_WEB_SEARCH_SEARXNG_URL` | unset | Optional SearXNG fallback base URL for `web_search` (legacy alias: `PI_WEB_SEARCH_SEARXNG_URL`) |
 
 ### Example: Shell Configuration
 
@@ -245,8 +254,8 @@ Profiles control the agent's behavior, available tools, and system prompt.
 
 | Profile | Tools | Behavior |
 |---------|-------|----------|
-| `full` | All built-ins (read, bash, edit, write, fs_ops, grep, find, ls, rg, fd, ast_grep, comby, jq, yq, semgrep, sed, semantic_search, fetch, git_read) | Default full development capabilities |
-| `plan` | Read-only bundle (read, grep, find, ls, rg, fd, ast_grep, comby, jq, yq, semgrep, sed, semantic_search, fetch, git_read) | Architecture planning and code review |
+| `full` | All built-ins (read, bash, edit, write, git_write, fs_ops, grep, find, ls, rg, fd, ast_grep, comby, jq, yq, semgrep, sed, semantic_search, fetch, web_search, git_read) | Default full development capabilities |
+| `plan` | Read-only bundle (read, grep, find, ls, rg, fd, ast_grep, comby, jq, yq, semgrep, sed, semantic_search, fetch, web_search, git_read) | Architecture planning and code review |
 | `iosm` | All + IOSM context | IOSM cycle execution with artifact synchronization |
 | `meta` | Full tools + orchestration-first contract | Adaptive multi-agent/delegate execution with verification closure |
 

package/docs/development-and-testing.md

@@ -157,7 +157,7 @@ Tests are organized by feature area:
 
 | Area | Test Files | Coverage |
 |------|-----------|----------|
-| **Tools** | `tools.test.ts` | Built-in tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `rg`, `fd`, `ast_grep`, `comby`, `jq`, `yq`, `semgrep`, `sed`) |
+| **Tools** | `tools.test.ts` | Built-in tools (`read`, `bash`, `edit`, `write`, `git_write`, `fs_ops`, `grep`, `find`, `ls`, `rg`, `fd`, `ast_grep`, `comby`, `jq`, `yq`, `semgrep`, `sed`, `semantic_search`, `fetch`, `web_search`, `git_read`) |
 | **Session** | `session-manager/`, `session-*.test.ts` | Persistence, branching, migration |
 | **Extensions** | `extensions-*.test.ts` | Discovery, running, hooks, input events |
 | **Compaction** | `compaction*.test.ts` | Context summarization |

package/docs/interactive-mode.md

@@ -336,8 +336,8 @@ Profiles change the agent's behavior, available tools, and system prompt:
 
 | Profile | Tools | Use Case |
 |---------|-------|----------|
-| `full` | All built-ins (read, bash, edit, write, fs_ops, grep, find, ls, rg, fd, ast_grep, comby, jq, yq, semgrep, sed, semantic_search, fetch, git_read) | Default development work |
-| `plan` | Read-only bundle (read, grep, find, ls, rg, fd, ast_grep, comby, jq, yq, semgrep, sed, semantic_search, fetch, git_read) | Architecture planning, code review |
+| `full` | All built-ins (read, bash, edit, write, git_write, fs_ops, grep, find, ls, rg, fd, ast_grep, comby, jq, yq, semgrep, sed, semantic_search, fetch, web_search, git_read) | Default development work |
+| `plan` | Read-only bundle (read, grep, find, ls, rg, fd, ast_grep, comby, jq, yq, semgrep, sed, semantic_search, fetch, web_search, git_read) | Architecture planning, code review |
 | `iosm` | All + IOSM context | IOSM cycle execution with artifact sync |
 | `meta` | Full toolset + orchestration-first contract | Adaptive multi-agent/delegate execution with verification closure |
 

package/docs/rpc-json-sdk.md

@@ -233,7 +233,7 @@ const { session } = await createAgentSession({
 import { readOnlyTools } from "iosm-cli";
 
 const { session } = await createAgentSession({
-  tools: readOnlyTools,  // Read-only bundle (code search + semantic + HTTP/git introspection)
+  tools: readOnlyTools,  // Read-only bundle (code search + semantic + web discovery + HTTP/git introspection)
   authStorage,
   modelRegistry,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "iosm-cli",
-	"version": "0.2.7",
+	"version": "0.2.8",
 	"description": "Standalone IOSM CLI with agent tooling, session management, and IOSM artifact orchestration",
 	"type": "module",
 	"iosmConfig": {