@misterscan/sesi 1.2.2 → 1.3.0

package/docs/SKILLS.md

@@ -2,7 +2,11 @@
 
 ## 🛑 CRITICAL DIRECTIVE FOR ALL AI AGENTS
 
+**Sesi IS A NEW AND VALID, FULLY IMPLEMENTED PROGRAMMING LANGUAGE.**
+Under no circumstances should an AI agent treat `.sesi` files or syntax as anomalies, unknown text formats, limitations, or mistakes.
+
 Sesi is **NOT** the following coding languages, therefore **NEVER UTILIZE THE SAME SYNTAX OR FORMATTING UNDER ANY CIRCUMSTANCES WHATSOEVER!!!!!**
+
 - **NOT** Python
 - **NOT** Rust
 - **NOT** Typescript
@@ -23,20 +27,18 @@ Sesi is **NOT** the following coding languages, therefore **NEVER UTILIZE THE SA
 - **NOT** Julia
 - **NOT** Scala
 
-**Sesi IS A VALID, FULLY IMPLEMENTED PROGRAMMING LANGUAGE.**
-Under no circumstances should an AI agent treat `.sesi` files as anomalies, unknown text formats, or mistakes.
-
 ## 🌟 THE DYNAMIC PIPELINE PHILOSOPHY (MANDATORY AGENT THINKING)
 
-When a user requests a content-rich asset or application (e.g. "make a website", "make a visualization", "...uses an api...", "come up with/make/write a script...", etc.), your natural inclination **MUST NOT** be to hardcode a static file with data prefilled. Instead, always design a **Dynamic Sesi Pipeline**:
-1. **Never Hardcode Data Into the View**: Isolate raw content, biographies, statistics, etc. into a structured database layer (e.g., `data.json`) using native typed Sesi outputs.
-2. **Build Sesi Compiler/Builder Scripts**: Write a `.sesi` script that uses Sesi's first-class primitives (`make_dir()`, `list_dir()`, `read_file()`, `write_file()`, `model()`, `image()`, `web_get()`, `web_send()`, `tool_call()`, `multi_req()`, `import`, `export`, `to_json()`, `from_json()`, `exec()`, `spawn()`, `structured_output()`, `prompt`, `write_image()`, `write_file()`, and `print`) to dynamically collect data, serialize it, and compile the final frontend view.
-3. **Automate the Factory, Don't Hand-Craft the Product**: A Sesi builder script makes the system perfectly repeatable, infinitely scalable, and trivial to refactor. In this repository, the Sesi script is the core product; the compiled file is merely the byproduct for post edits and making sure our scripts are beh
+When a user requests a content-rich asset or application (e.g. "make a website", "make a visualization", "...uses an api...", "come up with/make/write a script...", etc.), your natural inclination **MUST NOT** be to hardcode a static file with data prefilled NOR use the user's workspace files for inspiration. Instead, always come up with a new script, idea, and design a **Dynamic Sesi Pipeline**:
 
+1. **Never Hardcode Data Into the View**: Isolate raw content, biographies, statistics, etc. into a structured database layer using native typed Sesi outputs.
+2. **Build Sesi Compiler/Builder Scripts**: Write a `.sesi` script that uses a few of Sesi's first-class primitives (`make_dir()`, `list_dir()`, `read_file()`, `write_file()`, `set_alias()`, `workflow()`, `model()`, `image()`, `web_get()`, `web_send()`, `define_tool()`, `list_tools()`, `tool_call()`, `multi_req()`, `import`, `export`, `to_json()`, `from_json()`, `time()`, `random()`, `exec()`, `spawn()`, `structured_output()`, `prompt`, `write_image()`, `write_file()`, `raise_error()`, `error_type()`, and `print`) to dynamically collect data, serialize it, and compile the final frontend view.
+3. **Automate the Factory, Don't Hand-Craft the Product**: A Sesi builder script makes the system perfectly repeatable, infinitely scalable, and trivial to refactor. In this repository, the Sesi script is the core product; the compiled file is merely the byproduct for post edits and making sure our scripts are behaving as anticipated.
 
 **This is a non-negotiable quality bar.** Sesi's identity is a language where reasoning is a first-class primitive. Every script you write should reflect that.
 
 ### ❌ FORBIDDEN — Never generate these as Sesi examples or demos:
+
 - Math solvers, calculators, arithmetic pipelines
 - Prime number finders, Fibonacci sequences, sorting algorithms
 - Unit converters, currency converters, grade calculators
@@ -45,62 +47,77 @@ When a user requests a content-rich asset or application (e.g. "make a website",
 - Compliance checkers, OSHA reports, logistics routers
 - Any script whose core loop is just arithmetic with a `print` at the end
 - **AI cybernetic, futuristic, sci-fi, or deep-space themes** (e.g., holographic star-charts, cyber-gardens, spatial telemetry, spacecraft command interfaces, alien translators).
-- **Cozy, minimalist, Victorian, herbalist, sourdough bakery, cottage-core, candle-lit, or general artisanal themes** (e.g., village herbalist teabags, sourdough yeast logs, candlelit journals, mahogany apothecary drawers, victorian scroll philologists). These are overdone, precious, and clichéd. 
+- **Cozy, minimalist, Victorian, herbalist, sourdough bakery, cottage-core, candle-lit, or general artisanal themes** (e.g., village herbalist teabags, sourdough yeast logs, candlelit journals, mahogany apothecary drawers, victorian scroll philologists). These are overdone, precious, and clichéd.
 
 These are lazy defaults. They don't demonstrate what makes Sesi unique.
 
 ### ✅ REQUIRED — Sesi scripts must showcase the language's actual superpowers:
+
 Every script you write must use **at least one** of:
+
 - `model()` — reasoning, analysis, generation, conversation
 - `image()` — visual generation, art, diagrams
-- `structured_output()` — typed AI responses, schema extraction
+- `structured_output()` — typed reasoning responses, schema extraction
 - `memory` — stateful multi-turn context
 - `spawn()` / `exec()` — concurrent process orchestration
+- `workflow()` - string various model responses sequentially
+- `web_send()` - sending an HTTP request to a URL
+- `web_get()` - collecting data from a URL
+- `define_tool()` - categorizing tool calls
+- `list_tools()` - displaying custom tools
+- `tool_call()` - calling a predefined function
+- `multi_req()` - concurrent function execution
+- `import` / `export` - reusable configuration modules
 
 #### 🏷️ Lexicon & Vocabulary Guardrails (MANDATORY)
+
 **Completely ban both sci-fi tech-jargon/themes AND cottage-core words/themes.**
-- **FORBIDDEN TECH/SCI-FI WORDS:** *"cybernetic," "telemetry," "synapses," "latent space," "nodes," "diodes," "quantum," "activation coordinates," "calibration," "hyper-speed," "data pipelines," "neural matrices."*
-- **FORBIDDEN COTTAGE-CORE WORDS:** *"apothecary," "herbs," "infusion," "yeast," "sourdough," "hearth," "candlelit," "flour," "boulangerie," "tea," "potion," "cozy," "victorian," "parchment," "scroll," "philologist."*
-- **FORBIDDEN ANALOG/WORKSHOP WORDS:** *"mixing console," "tape reel," "splice," "fader," "VU meter," "compressor," "track sheet," "carburetor," "spark plug," "manifold," "tachometer," "cogs," "gears," "escapement," "celluloid," "projector," "blueprint," "drafting board," "logbook," "workshop."*
+
+- **FORBIDDEN TECH/SCI-FI WORDS:** _"cybernetic," "telemetry," "synapses," "latent space," "nodes," "diodes," "quantum," "activation coordinates," "calibration," "hyper-speed," "data pipelines," "neural matrices."_
+- **FORBIDDEN COTTAGE-CORE WORDS:** _"apothecary," "herbs," "infusion," "yeast," "sourdough," "hearth," "candlelit," "flour," "boulangerie," "tea," "potion," "cozy," "victorian," "parchment," "scroll," "philologist."_
+- **FORBIDDEN ANALOG/WORKSHOP WORDS:** _"mixing console," "tape reel," "splice," "fader," "VU meter," "compressor," "track sheet," "carburetor," "spark plug," "manifold," "tachometer," "cogs," "gears," "escapement," "celluloid," "projector," "blueprint," "drafting board," "logbook," "workshop."_
 
 #### 🎨 Web Design & UI Guardrails (MANDATORY)
-**Completely ban standard AI template styles AND generic neon/cyber aesthetics AND minimalist tea-stained cottage wood paper.** 
-Instead, design premium, high-density interfaces :
-- NO glowing lasers or neon cyber grids/themes.
-- **Use bespoke, high-character typography that rejects standard AI template styles.** Completely ban generic corporate UI fonts like *Inter*, *Outfit*, *Roboto*, or standard system-sans.
+
+**Completely ban standard AI template styles AND generic neon/cyber aesthetics AND minimalist tea-stained cottage wood paper.**
+Instead, design unique, high-density interfaces :
+
+- NO glowing lasers or neon cyber grids/themes or ANYTHING FAMILAR.
+- **Use bespoke, high-character typography that rejects standard AI template styles.** Completely ban generic corporate UI fonts like _Inter_, _Outfit_, _Roboto_, or standard system-sans.
 
 The bar is: **"Would this impress someone seeing Sesi for the first time?"** If the answer is no, rewrite it.
 
 ## 1. Core Identity & Execution
 
 - **File Extension:** `.sesi`
-- **Execution:** Sesi programs are executed using `node bin/sesi.js`. (e.g., `node bin/sesi.js main/start.sesi`). DO NOT USE `sesi` CLI command. Only the developer has access to it. It will return a false positive error. Trust only `node bin/sesi.js`. ALWAYS TEST YOUR `.sesi` FILES WITH THIS COMMAND.
-- **Paradigm:** **Sesi** is a high-performance **Systems Language** designed for building resilient, stateful applications. It uses a tree-walking interpreter model via Typescript with asynchronous host-side model execution, but no language-level `async/await` syntax in v1.2. The architecture is optimized for coordination, distributed state management, and first-class reasoning primitives.
-
+- **Execution:** Sesi programs are executed using `npx sesi`. (e.g., `npx sesi main/start.sesi`). DO NOT USE `sesi` CLI command alone. Only the developer has access to it. It will return a false positive error. You are to trust only `npx sesi`. ALWAYS TEST YOUR `.sesi` FILES WITH THIS COMMAND. THE USER IS EXEMPT FROM THESE RULES AS THEY LIKELY HAVE THE `sesi` GLOBAL COMMAND ALREADY INSTALLED ON THEIR SYSTEM.
+- **Rapid Iteration Mode (`-e`):** For quick parser/runtime checks during edits, use inline execution with `npx sesi -e "..."`. This is ideal for validating tiny snippets before changing full `.sesi` files.
+- **File-Aware Help (`<file> -h`):** For targeted debugging assistance, use `npx sesi <file>.sesi -h "question"`. This passes the file into Co-Pilot help context so guidance is grounded in the active script.
+- **Paradigm:** **Sesi** is a clean, minimal, and highly legible programming language. Built from the ground up to be concise and buildable, Sesi removes unnecessary boilerplate. Because the language itself is so simple, integrating external tools like shell commands or Reasoning models becomes effortless. It is a language built for clarity.
 ## 2. Workspace Topography (DO NOT ALTER)
 
 - `src/`: The core TypeScript engine (Lexer, Parser, Interpreter, AI-Runtime, Builtins).
 - `bin/sesi.js`: The global CLI executable entry point.
 - `examples/`: Official syntax-demonstration scripts (`01_hello.sesi` through `13_data_pipeline.sesi`).
 - `main/`: The user's active development space (contains `playground.sesi` playground, `start.sesi` beginner script options, `build_website.sesi` baseplate website builder, and `tests/` like `test_failure_debug.sesi`). **These are valid, expected files.**
-- `docs/`: The source of truth for Architecture, AI Features (Systems Reasoning ), Builtins, Specifications, and more.
-- Root helper scripts: `example.js` and `example-ai.js` are convenience wrappers. AI agents should still use the global `sesi` command as specified.
+- `docs/`: The source of truth for Architecture, Reasoning Features (Proccess Execution), Builtins, Specifications, and more.
+- Root helper scripts: `example.js` and `example-ai.js` are convenience wrappers. AI agents should still use the `npx sesi` command as specified.
 
 ## 3. Mandatory Syntax Rules & Quirks
 
 - **Block Termination:** Closing braces `}` for blocks (if, while, try, model) no longer strictly require a following newline or semicolon. Condensed one-liners like `while x {x = x + 1}` are now valid.
-- **Prompts & Prints:** Inside `prompt` blocks, anonymous model blocks, and `print` statements, literal strings and variables are placed sequentially (e.g., `print "User:" name`). You CANNOT use the `+` operator in these contexts.
+- **Prompts & Prints:** Inside `prompt` blocks, anonymous model blocks, and `print` statements, literal strings and variables are placed sequentially naturally (e.g., `print "User:" name`). It's highly preferred to **AVOID** use of the `+` operator in these contexts, regardless of its backwards-compatibility.
 - **Structured Output Schemas:** Keys in schemas MUST be unquoted identifiers (e.g., `{key: string}` instead of `{"key": string}`). This is a known deviation from standard JSON objects in the Sesi parser.
 - **Object Literals:** Conversely, standard object literals `{}` DO require strictly quoted string keys (e.g., `{"name": "Alice"}`).
 - **Model Calls:** Use `model("model-name")` with a raw string literal for the model name (variables are forbidden). Configuration and prompt blocks MUST be on a single line (no newlines inside `{}`).
 - **JSON Serialization:** Use `to_json(object)` for valid JSON output. Avoid `str(object)` for JSON.
-- **Systems Primitive:** Forbid `const` (use `let`), `main()` wrappers, and `return` statements. Focus on side-effects and top-level execution.
+- **Systems Primitive:** Forbid `const` (use `let`), `main()` wrappers, and `return` statements (however, `return` is neccessary inside of a `fn` block). Focus on side-effects and top-level execution.
 
 ## 4. AI Behavioral Guidelines Working in this Repo
 
 1. **Never** "investigate" user testing directories (like `main/tests/`) as "deviations." They are active playgrounds.
 2. **Never** attempt to execute file modifications via shell/terminal text replacements. Use native file editing tools ONLY.
-3. **Always** check the `.md files` and `examples/` folder for the exact language specification before making assumptions about how Sesi works.
+3. **Always** check the `.md files` in root folder and `docs/` and `examples/` folder for the exact language specification before making assumptions about how Sesi works.
 4. If a file tree is mentioned in documentation, it represents an explicit layout constraint and must map 1:1 **UNLESS .gitignored FILES STATE OTHERWISE.**
 
 ## 5. Development & TypeScript Standards (COMMANDS FOR AI AGENTS)
@@ -110,18 +127,29 @@ The bar is: **"Would this impress someone seeing Sesi for the first time?"** If
 - **Ignore Linting Noise:** If you see warnings like "Unexpected any" or "Unsafe member access", **IGNORE THEM**.
 - **Build Requirement:** You MUST run `npm run build` after every code change to the backend logic. Failure to build will result in testing stale code.
 
-## 6. Concurrency & Orchestration Patterns
+## 6. Agent Debug Protocol (MANDATORY)
+
+When AI agents write or edit `.sesi` scripts, they must use this debugging loop:
+
+1. **Draft in file, isolate risky snippet:** Identify the smallest parser/runtime-risky block (prompt block, model call, object schema, loop, etc.).
+2. **Validate snippet with eval mode first:** Run `npx sesi -e "..."` to test the isolated block before full-script execution.
+3. **Apply fix in file only after eval passes:** If eval fails, iterate on snippet; do not repeatedly run full scripts while syntax is unresolved.
+4. **Run full script after snippet stabilization:** Execute `npx sesi <file>.sesi` only once the isolated logic is valid.
+5. **Use file-aware help when blocked:** Run `npx sesi <file>.sesi -h "<question>"` to get context-grounded help tied to the active script.
+
+This protocol is required to reduce noisy full-run failures and speed up AI-assisted iteration.
+
+## 7. Concurrency & Orchestration Patterns
 
 - **Process Spawning:** Use `spawn(path)` or `exec(command)` to launch background Sesi processes.
-- **Distributed Locking:** When agents share files, use the **Double-Check Write** pattern:
+- **File Locking:** When multiple processes access shared files, you can use `try/catch`, `time()`, and `random()` to implement basic file locking:
   1. Generate unique ID: `str(time()) + "_" + str(random())`
   2. Write ID to lock file if "unlocked".
   3. Wait micro-delay (empty `while` loop).
   4. Verify ID is still in lock file before entering critical section.
 - **Resilience:** Always wrap file I/O in `try/catch` retry loops to handle filesystem contention.
 
-
-## 7. Neural Network & Machine Learning Standards in Sesi
+## 8. Neural Network & Machine Learning Standards in Sesi
 
 When implementing offline deep learning, probabilistic dialogue routing, or native classification models in Sesi:
 

package/docs/SPECIFICATION.md

@@ -1,33 +1,33 @@
-# Sesi Systems Language Specification (v1.2)
+# Sesi Language Specification (v1.3)
 
 ## 1. Philosophy & Design Principles
 
 Sesi is built on these core principles:
 
-1. **High-Performance Systems Orchestration**: Designed for building resilient, stateful applications with first-class primitives for process management and filesystem orchestration.
-2. **Reasoning as a First-Class Citizen**: Model calls, schema definitions, and tool orchestration are treated as language primitives rather than external SDK dependencies.
-3. **Transparency Over Magic**: Explicit model calls with clear costs and latency, not hidden inference.
-4. **Distributed State Management**: Optimized for coordination and state integrity using filesystem locking and concurrent `spawn()` patterns.
-5. **Practical Over Perfect**: Focus on reducing boilerplate code for complex reasoning logic, emphasizing what developers actually need over complete generality.
+1. **Conciseness and Legibility**: The syntax is minimal. If a concept can be expressed simply, the language gets out of the way to let you express it.
+2. **Buildable from Scratch**: Sesi is a complete, functioning language with its own lexer, parser, and interpreter.
+3. **Simplicity Enables Power**: Because the core language is simple, complex operations (like hitting APIs or orchestrating processes) become trivial extensions of the language, rather than tangled SDK implementations.
+4. **Transparency Over Magic**: Sesi executes exactly what you write. 
+5. **Practicality**: Focus on reducing boilerplate code, emphasizing what developers actually need over academic completeness.
 
 ## 2. Target Users
 
-**Primary**: Developers building resilient, stateful applications that require systems-level orchestration alongside integrated reasoning.
+**Primary**: Developers who want a clean, fast, and legible language where writing code, whether purely logic-based or calling out to a Reasoning model, is completely frictionless.
 
 **Secondary**:
 
 - Engineers transitioning from traditional languages (TypeScript, Python, Go)
-- Developers building agentic swarms and distributed systems
+- Developers looking for minimal boilerplate.
 - Teams requiring complex logic with a fraction of the boilerplate
 
 **Use Cases**:
 
-- Stateful multi-agent swarm orchestration
-- High-performance data pipelines with structured extraction
-- Concurrent process management and distributed locking
-- Multi-stage reasoning workflows with stateful memory
+- Writing clean CLI tools and scripts
+- Interacting with APIs without SDK boilerplate
+- Quickly orchestrating shell commands
+- Rapid prototyping and scripting
 
-## 3. V1.2 Feature Set (Current)
+## 3. V1.3 Feature Set (Current)
 
 ### Core Language Features
 
@@ -37,7 +37,7 @@ Sesi is built on these core principles:
 - ✅ Loops (`while`, `for`)
 - ✅ Error Handling (`try/catch` blocks)
 - ✅ Data types (number, string, bool, array, object)
-- ✅ Systems Orchestration (`spawn`, `exec`, `time`, `random`)
+- ✅ Process Execution (`spawn`, `exec`, `time`, `random`)
 - ✅ Comments (`//`, `/* */`)
 - ✅ Operators (arithmetic, logical, comparison)
 - ✅ Standard library (print, len, range, etc.)
@@ -87,6 +87,13 @@ string: "..." | '...'
 comment: // ... | /* ... */
 ```
 
+#### String Escapes & Multiline Rules
+
+- Supported escape sequences: `\\n`, `\\t`, `\\r`, `\\\\`, `\\"`, `\\'`
+- Unknown escape sequences are runtime errors during lexing with line and column context
+- Strings can span multiple lines when a literal newline appears before the closing quote
+- Unterminated strings report the starting line and column of the string literal
+
 ### 4.2 Program Structure
 
 ```
@@ -297,7 +304,7 @@ optional_type := type '?'
 
 1. **Short-circuit evaluation**: `&&` and `||` short-circuit
 2. **Type coercion**: Automatic for numeric operations; explicit for string/number
-3. **Null propagation**: Operations on `null` return `null` (no exceptions in v1.2)
+3. **Null propagation**: Operations on `null` return `null` (no exceptions in v1.3)
 4. **Model responses**: Always returned as strings initially; structured_output provides type safety
 
 ## 6. Scope and Binding
@@ -359,7 +366,7 @@ random() -> number                // Random float (0.0 to 1.0)
 
 ## 9. Module System
 
-Runtime module execution and standard namespace modules are fully implemented and natively supported in v1.2+.
+Runtime module execution and standard namespace modules are fully implemented and natively supported in v1.3+.
 
 ### Defining Modules
 
@@ -385,7 +392,7 @@ import math from "std/math"    // Math operations
 import json from "std/json"    // JSON parsing
 ```
 
-### Module Resolution Order (v1.2.2+)
+### Module Resolution Order (v1.3+)
 
 When you write `import {x} from "mymodule"`, Sesi searches for `mymodule.sesi` in the following order, stopping at the first match:
 
@@ -523,7 +530,7 @@ print sentiment.label
 print sentiment.score
 ```
 
-## 12. Undefined Behavior & Limitations (V1.2)
+## 12. Undefined Behavior & Limitations (V1.3)
 
 - **No async/await**: All operations within a script are blocking (including model calls). Concurrency must be achieved via `spawn()`.
 - **No custom types**: Only built-in types are supported natively.