toolang 0.2.4__tar.gz → 0.2.5__tar.gz

{toolang-0.2.4 → toolang-0.2.5}/.gitignore

@@ -21,3 +21,5 @@ wheels/
 archive/
 scratch/
 reference/generated/
+
+.zed

{toolang-0.2.4 → toolang-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: toolang
-Version: 0.2.4
+Version: 0.2.5
 Summary: A programming language and runtime for agents
 Project-URL: Homepage, https://toolang.ai/
 Project-URL: Documentation, https://toolang.ai/docs
@@ -224,7 +224,7 @@ Requires-Dist: python-dotenv<2,>=1.0
 Requires-Dist: python-frontmatter>=1.1.0
 Requires-Dist: rich<15,>=14
 Requires-Dist: tomli-w>=1.2.0
-Requires-Dist: tree-sitter-toolang>=0.0.16
+Requires-Dist: tree-sitter-toolang>=0.1.3
 Requires-Dist: tree-sitter<0.26,>=0.24
 Requires-Dist: typer<1,>=0.16
 Requires-Dist: uvicorn<1,>=0.35
@@ -237,7 +237,7 @@ Description-Content-Type: text/markdown
 
 # Toolang
 
-A programming language and runtime for agents.
+A description language and runtime for agents.
 
 Tool calling turned LLMs from chatbots into agents. Toolang makes agents easy to build, run, and share.
 

{toolang-0.2.4 → toolang-0.2.5}/README.md

@@ -4,7 +4,7 @@
 
 # Toolang
 
-A programming language and runtime for agents.
+A description language and runtime for agents.
 
 Tool calling turned LLMs from chatbots into agents. Toolang makes agents easy to build, run, and share.
 

{toolang-0.2.4 → toolang-0.2.5}/docs/api.md

@@ -82,6 +82,7 @@ toolang list
 PY_LOG=toolang.run=info toolang ./examples/invoke-playground.too summarize "Summarize this workspace"
 toolang ./examples/invoke-playground.too --help
 toolang ./examples/invoke-playground.too summarize "Summarize this workspace"
+toolang ./examples/file-agent.too --inbox ./inbox
 toolang run alice
 toolang run brice/alice
 toolang run https://toolang.ai/alice.too
@@ -136,7 +137,8 @@ Foreground runtime port selection depends on the agent mode:
 | --- | --- | --- |
 | Resident | Local managed name such as `alice` | Reuse the agent's last port when available, otherwise choose from `7001-7999` |
 | Visiting | Remote selector such as `brice/alice` or `https://toolang.ai/alice.too` | Reuse the visiting root's last port when available, otherwise choose an OS temporary port |
-| Roaming | Local `.too` path invocation | No HTTP runtime port; the thunk is invoked directly |
+| Roaming invoke | Local `.too` path with a thunk name | No HTTP runtime port; the thunk is invoked directly |
+| Roaming file runtime | Local `.too` path with `--inbox` and no thunk name | Choose an OS temporary port |
 
 
 ## Invoke Surface
@@ -169,9 +171,10 @@ Behavior:
 - `NAME=VALUE` sets one thunk named param when `NAME` matches the thunk signature
 - `INPUT` rules:
   - `TEXT` adds one text part; use `@@TEXT` for literal text beginning with `@`
-  - `@PATH` adds one path-based part; `.txt` and `.md` paths become text parts
+  - `@PATH` adds one path-based part; text-like paths become text parts
   - image extensions such as `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`, and `.svg` infer image parts
   - audio extensions such as `.mp3`, `.wav`, `.m4a`, `.aac`, `.ogg`, and `.flac` infer audio parts
+  - video extensions such as `.mp4`, `.mov`, `.m4v`, `.webm`, `.mkv`, `.avi`, `.mpeg`, `.mpg`, `.3gp`, and `.ogv` infer video parts
   - all other path extensions infer generic file parts
 - `--` ends option parsing so later arguments stay `INPUT` values
 - `--option` is reserved for Toolang runtime options
@@ -179,6 +182,30 @@ Behavior:
 - key execution events are recorded in `runs.db` for script runs just like chat,
   task, and chore runs
 
+## File Request Runtime
+
+Roaming scripts can also start a foreground file request runtime without naming
+a thunk:
+
+```bash
+toolang SCRIPT --inbox PATH [--inbox PATH...]
+```
+
+Behavior:
+
+- `SCRIPT` is materialized into its sibling `.toolang` roaming root.
+- Each `--inbox` value must name an existing directory.
+- Startup enables `runner.file`, `trigger.file`, and `trigger.watch`.
+- Startup requires a thunk named `file` that accepts message input and has no
+  required parameters.
+- Files already present in an inbox at startup are eligible for processing.
+- Newly discovered stable files are passed to the `file` thunk using the same
+  file input part rules as `@PATH`.
+- File request progress is stored in `.runtime/files.db`.
+- Finished, failed, and canceled file fingerprints are not automatically retried.
+- When a thunk name is present, such as `toolang SCRIPT file ...`, Toolang uses
+  normal one-shot thunk invocation.
+
 
 ## Runtime Commands
 

{toolang-0.2.4 → toolang-0.2.5}/docs/caps.md

@@ -64,7 +64,7 @@ Scope tells where a cap is available:
 
 | Origin | Meaning |
 | --- | --- |
-| `local` | Local authored content, including inline program declarations and local files or directories |
+| `local` | Local authored content, including inline program caps and local files or directories |
 | `remote` | A remote authored cap fetched through a ref |
 
 Runtime APIs expose effective caps. They do not expose every authored source

{toolang-0.2.4 → toolang-0.2.5}/docs/concepts.md

@@ -93,8 +93,8 @@ Caps are assembled from the materialized root and source:
 | `visiting` | Inline caps and referenced caps from the materialized remote source |
 | `roaming` | Source-local `toolang.toml`, inline caps, and referenced caps from the local `.too` source |
 
-Caps do not have a separate placement allowlist. A program declaration or
-reference makes a cap available to that program, but it does not make the cap
+Caps do not have a separate placement allowlist. A program cap or reference
+makes a cap available to that program, but it does not make the cap
 effective for every thunk by itself.
 
 
@@ -159,8 +159,8 @@ through ordered sets.
 Placement provides a default resource set. CLI options may override or adjust
 that default for one activation. The result is the activation set.
 
-Programs may also declare or reference resources. Those declarations form a
-program set. Program resources are not automatically effective for every thunk.
+Programs may also define inline caps or reference resources. Those items form
+a program set. Program resources are not automatically effective for every thunk.
 
 Thunk directives compute the effective set from the activation set:
 

{toolang-0.2.4 → toolang-0.2.5}/docs/execution.md

@@ -32,6 +32,12 @@ It stores:
 documents. It is used for atomic job claims and completion bookkeeping; it is
 not the transcript or run-history store.
 
+`.runtime/files.db` stores file request claims for inbox directories. It records
+the watched root, relative path, absolute path, size, mtime, content
+fingerprint, terminal status, run id, timestamps, and terminal error. It is used
+for deduplicating file fingerprints and completion bookkeeping; it is not the
+transcript or run-history store.
+
 
 ## Durable Records
 
@@ -53,7 +59,12 @@ not the transcript or run-history store.
 
 Toolang-owned run ids use `run_<id>`, where `<id>` is encoded with the `run`
 id family. Thread ids use `<kind>_<id>`, such as `tsk_3nprht9x`,
-`chr_xy1234ab`, or `web_def456gh`.
+`chr_xy1234ab`, `file_def456gh`, or `web_def456gh`.
+
+File request runs use origin `file` and explicitly invoke the thunk named
+`file`. The run input stores the rendered file message, and run metadata stores
+the `invoke_parts` file attachment data plus the file request id and
+fingerprint.
 
 ### StepRecord
 

{toolang-0.2.4 → toolang-0.2.5}/docs/ids.md

@@ -73,11 +73,18 @@ The proposed full identities are:
 - chore thread: `chr_<id>`
 - web chat thread: `web_<id>`
 - TUI chat thread: `tui_<id>`
+- file request thread: `file_<full-path-sha256-prefix>`
+- script/invoke thunk thread: `thunk_<thunk-name>`
 - Telegram thread: `tg_<external_id>`
 - run id: `run_<id>`
 
-The bare `<id>` stays stable even when a file is renamed, moved, archived, or
-restored.
+For task and chore ids, the bare `<id>` stays stable even when the authored file
+is renamed, moved, archived, or restored.
+
+File request threads use the first 12 hex chars of the SHA-256 of the absolute
+source path, so new file fingerprints at the same path share a thread.
+Script/invoke runs are stable for the invoked thunk name; the default thunk uses
+`thunk_main`.
 
 
 ## Reversible Obfuscation

{toolang-0.2.4 → toolang-0.2.5}/docs/layout.md

@@ -91,6 +91,7 @@ Key paths:
 | `logs/<thunk>/<run_id>.log` | Per-run script invoke logs when `PY_LOG` is set |
 | `jobs.db` | Scheduler job projection and atomic job claims                |
 | `runs.db` | Threads, runs, steps, updates, and prompt blobs               |
+| `files.db` | File request claims, fingerprints, and completion state        |
 | `ids.json`     | Local id allocator state                                     |
 | `tools/`       | Per-tool plugin working directories                          |
 | `channels/`    | Per-channel plugin working directories                       |
@@ -127,4 +128,8 @@ Durable authored state lives in:
 - agent `archive/`
 
 Durable execution state does not live in authored files. It lives in
-`jobs.db` and `runs.db`.
+`jobs.db`, `runs.db`, and `files.db`.
+
+Inbox directories passed with `--inbox` are external user directories. Toolang
+does not write marker files into them; file request progress is recorded under
+the agent runtime room in `files.db`.

{toolang-0.2.4 → toolang-0.2.5}/docs/prepared-lock.md

@@ -437,7 +437,7 @@ Artifact buckets are:
 
 | Bucket | Meaning |
 | --- | --- |
-| `inline` | Files materialized from inline program declarations |
+| `inline` | Files materialized from inline program caps |
 | `ref` | Files materialized from program `use` refs |
 | `wired` | Files materialized from config refs |
 
@@ -485,9 +485,8 @@ Thunk fields follow grammar names:
 | `directives` | Thunk `directive` items |
 | `blocks` | Thunk `block` items |
 
-Use `directives`, not `overlays`, and `blocks`, not `messages`, in the lock
-format. Those names match `tree-sitter-toolang`; overlay and message concepts
-are runtime projections.
+Use `directives` and `blocks` in the lock format. Those names match
+`tree-sitter-toolang`; directive and message concepts are runtime projections.
 
 Type strings use the canonical source spelling from the grammar. Built-in
 types include `Text`, `Number`, `Boolean`, `Json`, and `Message`. User type

{toolang-0.2.4 → toolang-0.2.5}/docs/program.md

@@ -39,12 +39,12 @@ thunk pay:
 ```
 
 
-## Embedded Cap Declarations
+## Embedded Caps
 
-Program-level `psyche`, `service`, and `prompt` declarations are embedded inline caps.
+Program-level `psyche`, `service`, and `prompt` blocks are embedded inline caps.
 During prepare, Toolang materializes them into the agent-specific prepared cap
 set under `.caps/inline`, preserving the `.too` file as the definition
-source. This makes embedded declarations visible through cap APIs and WebUI
+source. This makes embedded caps visible through cap APIs and WebUI
 surfaces before any thunk selects them. The prepared cap has `form=inline`,
 `scope=here`, and `origin=local`.
 
@@ -347,9 +347,9 @@ thunk review(input: Message, path?: Path) -> ReviewResult:
 
 ### Scalar and Set Directives
 
-Directives are ordered set overlays on the activation set. The activation set is
+Directives are ordered set operations on the activation set. The activation set is
 computed before the program runs from placement defaults and CLI options.
-Program declarations and references form the program set.
+Program caps and references form the program set.
 
 | Form | Meaning |
 | --- | --- |
@@ -367,7 +367,7 @@ Rules:
 | `+=` | union the current set with named program-set items |
 | `-=` | subtract matching selectors from the current set |
 | `=` | intersect the current set with matching selectors |
-| ordered CSV | preserve declaration order |
+| ordered CSV | preserve source order |
 | no `default` keyword | `default` is treated like any other selector text |
 | model selectors | `models = ...` may use refs, aliases, globs, and bracket filters |
 | program-scoped additions | `+=` operands must name items from the program set |
@@ -503,9 +503,9 @@ The runtime expands the prompt before normal run-input assembly. The slash-style
 `/name ...` invocation remains the user-facing call shape.
 
 
-## Service Declarations
+## Service Caps
 
-`service` declarations use fenced markdown bodies. Service metadata lives in
+`service` caps use fenced markdown bodies. Service metadata lives in
 frontmatter inside that markdown.
 
 `service` frontmatter uses one minimal schema. `description` is the progressive

{toolang-0.2.4 → toolang-0.2.5}/examples/alice.too

@@ -3,22 +3,18 @@
 
 use skill briceyan/pdf-processing
 
-service context7: ```md
----
-description: Use when current library or framework documentation matters.
-transport: http
-target: https://mcp.context7.com/mcp
----
-
-Use this service when current library or framework documentation matters.
-Prefer it over stale recollection when the user asks about APIs, versions, or
-integration details.
-```
-
-psyche alice: ```md
-Be practical, concise, and source-aware.
-Prefer concrete next steps over broad explanations.
-```
+service context7:
+  description = Use when current library or framework documentation matters.
+  protocol = http
+  target = https://mcp.context7.com/mcp
+
+  Use this service when current library or framework documentation matters.
+  Prefer it over stale recollection when the user asks about APIs, versions, or
+  integration details.
+
+psyche alice:
+  Be practical, concise, and source-aware.
+  Prefer concrete next steps over broad explanations.
 
 thunk:
   Help the user directly.

toolang-0.2.5/examples/deep_search.too

@@ -0,0 +1,61 @@
+thunk expand_queries(in: Part[]):
+  Research question:
+  {{ _ }}
+
+  Turn this research question into 6 diverse web search queries.
+  Return one query per line. No bullets, no numbering.
+
+thunk search_web(in: Part[]):
+  tools = web_search/*
+
+  Query:
+  {{ _ }}
+
+  Search the web for this query.
+  Return a compact evidence bundle:
+  - query
+  - 3-5 useful results
+  - title, url, date if available
+  - one sentence on why it matters
+
+thunk extract_findings(in: Part[]):
+  Evidence bundle:
+  {{ _ }}
+
+  Extract durable findings from this evidence bundle.
+  Prefer source-backed claims.
+  Return concise bullets with URLs preserved.
+
+thunk synthesize_report(in: Part[]):
+  Findings:
+  {{ _ }}
+
+  Write a deep research brief from these findings.
+
+  Structure:
+  - Executive summary
+  - Key findings
+  - Conflicting or uncertain points
+  - Source notes
+  - Next search directions
+
+flow research(in: Text):
+  ## Expand the research question into diverse search queries
+  do expand_queries
+  ## Search the web for each query
+  each par 4 search_web
+  ## Keep evidence bundles that answer the research task
+  keep is_relevant
+  ## Rank the remaining evidence by relevance
+  rank 8: Return a numeric relevance score from 0 to 10. Higher is better.
+  ## Extract source-backed findings from each evidence bundle
+  each par 4 extract_findings
+  ## Synthesize the final research brief
+  do synthesize_report
+
+thunk is_relevant(in: Part[]):
+  Evidence bundle:
+  {{ _ }}
+
+  Decide whether this evidence bundle contains concrete information about agent workflow implementations.
+  Return only "keep" or "drop".

toolang-0.2.5/examples/file-inbox-indexer.too

@@ -0,0 +1,20 @@
+#!/usr/bin/env toolang
+
+# File request runtime example.
+#
+# Run:
+# mkdir -p inbox
+# toolang examples/file-inbox-indexer.too --inbox ./inbox
+#
+# Drop files into ./inbox. Each discovered file is sent to the `file` thunk.
+# The thunk appends a short text summary to the roaming agent home file:
+#
+# examples/.toolang/agents/file-inbox-indexer/outbox/index.md
+
+thunk file(in: Part[]):
+  tools = filesystem/*
+
+  user:
+    Process the current file request immediately. Do not ask for confirmation.
+    Append each file with its short text summary to `outbox/index.md` in the agent home.
+    After the file is written, reply with only: Indexed `<file name or path>`.

{toolang-0.2.4 → toolang-0.2.5}/examples/invoke-playground.too

@@ -4,22 +4,22 @@
 # It keeps the capabilities minimal and focuses on different thunk shapes.
 
 struct Summary:
-  title: string
-  summary: string
+  title: Text
+  summary: Text
 
 struct BulletList:
-  items: string[]
+  items: Text[]
 
-thunk summarize(_) -> Summary:
+thunk summarize(in: Part[]) -> Summary:
   Produce a compact summary with a short title and a short summary paragraph.
 
-thunk bullets(_) -> BulletList:
+thunk bullets(in: Part[]) -> BulletList:
   Extract the main points into short bullet items.
 
-thunk rewrite(_, tone?, audience?):
+thunk rewrite(in: Part[], tone?, audience?):
   Rewrite the input in the requested tone.
   Adjust depth and wording for the requested audience when it is provided.
 
-thunk slug(title) -> text:
+thunk slug(title) -> Text:
   Convert the provided title into a concise lowercase slug.
   Use hyphens between words and return only the slug text.

{toolang-0.2.4 → toolang-0.2.5}/examples/invoke.fixed-model.too

@@ -10,7 +10,7 @@
 
 use skill briceyan/review
 
-thunk gpt_only(_):
+thunk gpt_only(in: Part[]):
   model = openai/gpt-5
 
   Rewrite the input into one concise paragraph.

{toolang-0.2.4 → toolang-0.2.5}/examples/invoke.openrouter-smoke.too

@@ -17,27 +17,27 @@
 # Qwen3 Coder Next:
 #   toolang examples/invoke.openrouter-smoke.too qwen "Summarize this repository." --model qwen/qwen3-coder-next@openrouter
 
-thunk gpt(_):
+thunk gpt(in: Part[]):
   model = openai/gpt-5
 
   Summarize the input into three short technical bullet points.
 
-thunk claude(_):
+thunk claude(in: Part[]):
   model = anthropic/claude-sonnet-4.5
 
   Summarize the input into three short technical bullet points.
 
-thunk gemini(_):
+thunk gemini(in: Part[]):
   model = google/gemini-3.1-pro-preview
 
   Summarize the input into three short technical bullet points.
 
-thunk grok(_):
+thunk grok(in: Part[]):
   model = x-ai/grok-4.20
 
   Summarize the input into three short technical bullet points.
 
-thunk qwen(_):
+thunk qwen(in: Part[]):
   model = qwen/qwen3-coder-next
 
   Summarize the input into three short technical bullet points.

{toolang-0.2.4 → toolang-0.2.5}/examples/invoke.priority.too

@@ -14,7 +14,7 @@
 #     --model anthropic/claude-sonnet-4.5@openrouter \
 #     --model google/gemini-3.1-pro-preview@openrouter
 
-thunk rewrite(_):
+thunk rewrite(in: Part[]):
   model = openai/gpt-5, anthropic/claude-sonnet-4.5, google/gemini-3.1-pro-preview
 
   Rewrite the input for a technical audience.

{toolang-0.2.4 → toolang-0.2.5}/examples/invoke.simulated-history.memory.too

@@ -6,11 +6,11 @@
 #
 #   toolang examples/invoke.simulated-history.memory.too followup "What did I ask you to remember?"
 
-thunk followup(_):
+thunk followup(in: Part[]):
   recall = memory
 
-  context: none
-  instruct: none
+  context none
+  instruct none
 
   user:
     Remember that the deployment window is Friday morning.

{toolang-0.2.4 → toolang-0.2.5}/examples/invoke.simulated-history.none.too

@@ -6,9 +6,9 @@
 #
 #   toolang examples/invoke.simulated-history.none.too followup "What is my name?"
 
-thunk followup(_):
+thunk followup(in: Part[]):
   recall = none
-  context: none
+  context none
 
   user:
     My name is Ada.

toolang-0.2.5/examples/llm-wiki.too

@@ -0,0 +1,33 @@
+#!/usr/bin/env toolang
+
+# LLM wiki file request example.
+#
+# Run:
+# mkdir -p wiki-inbox
+# toolang examples/llm-wiki.too --inbox ./wiki-inbox
+#
+# Drop documents, images, audio, video, or other files into ./wiki-inbox.
+# The `file` thunk turns each file into a concise wiki page in:
+#
+# examples/.toolang/agents/llm-wiki/wiki/
+thunk file(in: Part[]):
+  tools = filesystem/*
+
+  user:
+    Process the current file request immediately. Do not ask for confirmation.
+    Maintain an LLM-readable wiki under `wiki/` in the agent home.
+
+  Write one concise Markdown page under `wiki/pages/` for this file.
+  Append one short link entry to `wiki/index.md`.
+
+  Each page should contain only useful text: a title, source reference when
+  visible, a compact summary, key facts, and searchable keywords.
+  After writing, reply with only: Wikified `<file name or path>`.
+
+thunk chat(in: Part[]):
+  tools = filesystem/*
+
+  user:
+    Answer from the wiki in the agent home. Read `wiki/index.md` first, then
+    read the relevant pages under `wiki/pages/` before answering.
+    If the wiki does not contain enough information, say what is missing.

{toolang-0.2.4 → toolang-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "toolang"
-version = "0.2.4"
+version = "0.2.5"
 description = "A programming language and runtime for agents"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -41,7 +41,7 @@ dependencies = [
     "rich>=14,<15",
     "tomli-w>=1.2.0",
     "tree-sitter>=0.24,<0.26",
-    "tree-sitter-toolang>=0.0.16",
+    "tree-sitter-toolang>=0.1.3",
     "typer>=0.16,<1",
     "uvicorn>=0.35,<1",
     "watchfiles>=1.1,<2",