@misterscan/sesi 1.2.2 → 1.3.0

package/docs/QUICKSTART.md

@@ -1,6 +1,8 @@
 # Quick Start Guide: Sesi Programming Language
 
-## Run a program:
+### Run a program
+
+Once Sesi is installed, you can run Sesi files globally:
 
 ```bash
 sesi main/start.sesi
@@ -8,6 +10,7 @@ sesi main/start.sesi
 
 ### Run Tests
 
+For devs working on Sesi, you can verify your backend edits with the built-in test suite:
 ```bash
 npm test
 ```
@@ -104,7 +107,7 @@ Get your key from [Google AI Studio](https://aistudio.google.com/app/apikey).
 Reasoning features allow passing configuration options via a block format before the prompt.
 
 ```sesi
-let response = model("gemini-3-flash-preview") {"temperature": 0.8, "max_tokens": 1000} {"What is 2 + 2?"}
+let response = model("gemini-3-flash-preview") {temperature: 0.8, max_tokens: 1000} {"What is 2 + 2?"}
 print response
 ```
 
@@ -129,7 +132,7 @@ print "Score: " analysis["score"]
 Like `model`, the `image` command takes configuration parameters.
 
 ```sesi
-let logo = image("gemini-3.1-flash-image-preview") {"ratio": '1:1', "size": 512, "temperature": 0.3, "max_tokens": 512} {"make a beautiful logo for the word Sesi"}
+let logo = image("gemini-3.1-flash-image-preview") {ratio: "1:1", size: "512", temperature: 0.3} {"make a beautiful logo for the word Sesi"}
 write_image("logo.png", logo)
 print "Generated image successfully!"
 ```
@@ -143,7 +146,7 @@ print response
 chat = chat "Assistant:" response
 ```
 
-### Concurrent Swarms
+### Concurrent Processes
 
 Sesi can orchestrate multiple concurrent scripts using the `spawn()` builtin.
 
@@ -167,6 +170,7 @@ from_json(path)    // Read a JSON file
 write_file(path, content) // Write text to a file
 write_image(path, content) // Write base64 encoded image to a file
 list_dir(path)     // List directory contents
+make_dir(path)     // Create a new directory
 spawn(path)        // Launch concurrent background process
 exec(command)      // Synchronous shell execution
 time()             // Unix timestamp (ms)
@@ -178,7 +182,7 @@ random()           // Random number (0-1)
 ```sesi
 type(value)        // Get type name
 str(value)         // Convert to string
-to_json(value)      // Convert to valid JSON string
+to_json(value)     // Convert to valid JSON string
 num(value)         // Convert to number
 bool(value)        // Convert to boolean
 ```
@@ -199,19 +203,41 @@ range(n)           // Create [0, 1, ..., n-1]
 ### Network & Concurrency
 
 ```sesi
-web_get(url, headers = {})     // Natively fetch from URL via HTTP GET
+web_get(url, headers = {})        // Natively fetch from URL via HTTP GET
 web_send(url, body, headers = {}) // Natively post body to URL via HTTP POST
-multi_req(array<function>)     // Run multiple tasks/requests physically in parallel
+multi_req(array<function>)        // Run multiple tasks/requests physically in parallel
+```
+
+### Reasoning
+
+```sesi
+workflow(steps, input)          // Run a multi-step reasoning workflow
+set_alias(alias, model)         // Register a custom local name for a model
+define_tool(name, fn, desc)     // Register a custom tool
+list_tools()                    // List custom tool names
+```
+
+### Error Handling
+
+```sesi
+error_type(type, message, data) // Create a custom error object
+raise_error(error)              // Throw an error
+```
+
+### Math
+
+```sesi
+exp(x)             // Exponential function
 ```
 
 ### Standard Library Modules
 
-Standard library features are available natively in **v1.2.0** using imports:
+Standard library features are available natively in **v1.2+** using imports:
 
 ```sesi
-import { PI, sqrt } from "std/math"
-import { sleep, now } from "std/time"
-import { stringify, parse } from "std/json"
+import {PI, sqrt} from "std/math"
+import {sleep, now} from "std/time"
+import {stringify, parse} from "std/json"
 ```
 
 ## Running Examples
@@ -239,10 +265,14 @@ sesi examples/14_folder_explainer.sesi
 # Image generation example
 sesi examples/15_image_generation.sesi
 
-# Advanced Version 1.2 features
+# Advanced Version 1.3 features
 sesi examples/16_modules.sesi
 sesi examples/17_http_client.sesi
 sesi examples/18_parallel_requests.sesi
+sesi examples/19_search_web.sesi
+sesi examples/20_model_aliases.sesi
+sesi examples/21_custom_tools.sesi
+sesi examples/22_reasoning_plus_custom_tools.sesi
 ```
 
 ## Common Patterns
@@ -284,8 +314,8 @@ let rejoined = join(words, "-")
 ### Reasoning Classification
 
 ```sesi
-fn classify(item: string) {print model("gemini-3-flash-preview")
-{"Classify as: FRUIT, VEGETABLE, or GRAIN. Item: " item}}
+fn classify(item: string) 
+{print model("gemini-3-flash-preview"){"Classify as: FRUIT, VEGETABLE, or GRAIN. Item: " item}}
 classify("apple")
 classify("carrot")
 classify("wheat")
@@ -296,12 +326,11 @@ classify("wheat")
 ### Print Intermediate Values
 
 ```sesi
-fn complex(x: number) {
-  let step1 = x * 2
-  print "Step 1:" str(step1)
-  let step2 = step1 + 10
-  print "Step 2:" str(step2)
-}
+fn complex(x: number) 
+{let step1 = x * 2
+print "Step 1:" str(step1)
+let step2 = step1 + 10
+print "Step 2:" str(step2)}
 complex(5)
 ```
 
@@ -331,15 +360,15 @@ else {print "Response: " response}
 
 ## Next Steps
 
-1. **Read the spec**: [SPECIFICATION.md](SPECIFICATION.md)
-2. **Learn about reasoning**: [SYSTEMS_REASONING.md](SYSTEMS_REASONING.md)
-3. **Understand architecture**: [ARCHITECTURE.md](ARCHITECTURE.md)
-4. **Check roadmap**: [ROADMAP.md](ROADMAP.md)
-5. **Study examples**: [examples/](/examples/)
+1. **Read the spec**: [SPECIFICATION.md](docs/SPECIFICATION.md)
+2. **Learn about reasoning**: [REASONING.md](docs/REASONING.md)
+3. **Understand architecture**: [ARCHITECTURE.md](docs/ARCHITECTURE.md)
+4. **Check roadmap**: [ROADMAP.md](docs/ROADMAP.md)
+5. **Study examples**: [examples/](examples/)
 
 ## Getting Help
 
-Sesi comes with an advanced, built-in **Interactive RAG Co-Pilot** right in your command line! Instead of static help messages, you can query Sesi directly about how to use any statement, standard library, or architectural pattern:
+Sesi comes with an advanced, built-in **Interactive Co-Pilot** right in your command line! Instead of static help messages, you can query Sesi directly about how to use any statement, standard library, or architectural pattern:
 
 ```bash
 # Ask the Sesi Co-Pilot for help directly
@@ -348,11 +377,35 @@ sesi --help "explain structured_output and give an example"
 sesi -h "how to spawn background processes?"
 ```
 
+You can also pass a file into the help context so the co-pilot can talk about that exact script:
+
+```bash
+sesi main/playground.sesi -h
+sesi main/playground.sesi -h "why is this failing?"
+```
+
+Other useful CLI options:
+
+```bash
+# Run a one-line snippet
+sesi -e "print 'hello'"
+
+# Encrypt or decrypt a script file
+sesi -encrypt my_script.sesi -p "my-password"
+sesi -decrypt my_script.sesi -p "my-password"
+
+# Disable sandbox protections for a run
+sesi main/start.sesi --local
+
+# Add extra allowed filesystem paths
+sesi main/start.sesi --allowed-paths ./docs,./examples
+```
+
 The co-pilot will dynamically index and train on Sesi's native repository database and retrieve full RAG context from our standard specification docs to generate a syntactically correct, 100% accurate, conversational answer in real-time!
 
 You can also:
 - Check documentation in [docs/](docs/)
-- Review examples in [examples/](/examples/)
+- Review examples in [examples/](examples/)
 - Read error messages carefully
 - Try simpler programs first
 
@@ -367,4 +420,4 @@ When reporting bugs:
 
 ---
 
-Happy programming with Sesi! 🚀
+Happy programming with Sesi! 🚀

package/docs/README.md

@@ -2,7 +2,7 @@
   <img src="favicon.ico" alt="Sesi Logo" height="100" />
 </p>
 
-<h1 align="center">Sesi: A High-Performance Systems Language</h1>
+<h1 align="center">Sesi: A Concise, Legible Programming Language</h1>
 
 <p align="center">
   <em>Pronounced "say-see" — What you say, you'll see.</em>
@@ -15,7 +15,13 @@
   <img alt="Framework" src="https://img.shields.io/badge/Node.js-Engine-success?logo=node.js">
 </p>
 
-**Sesi** is a high-performance **Systems Language** designed for building resilient, stateful applications. It provides first-class primitives for process management, filesystem orchestration, and integrated reasoning—enabling developers to build complex logic with a fraction of the boilerplate required by traditional languages.
+<p align="center">
+  <strong>Sesi</strong> 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.
+</p>
+
+<p align="center">
+  <a href="https://code-with-sesi.netlify.app/">Homepage</a>
+</p>
 
 ## Quick Start
 
@@ -32,6 +38,26 @@ sesi examples/08_model_call.sesi
 sesi examples.sesi
 ```
 
+Useful CLI shortcuts:
+
+```bash
+# Evaluate a quick snippet
+sesi -e "print 'hello'"
+
+# Ask the built-in co-pilot a question
+sesi -help "how do I use memory?"
+
+# Ask for help about a specific file
+sesi main/playground.sesi -h "why is this failing"
+
+# Encrypt or decrypt a script file
+sesi -encrypt my_script.sesi -p "my-password"
+sesi -decrypt my_script.sesi -p "my-password"
+
+# Run with sandbox restrictions disabled
+sesi main/start.sesi --local
+```
+
 # Local Execution (Development)
 
 If you choose not use the `sesi` command, use the helper npm scripts:
@@ -67,6 +93,40 @@ let code = model("gemini-3.1-pro-preview") {generateCode}
 print code
 ```
 
+## Security & Sandboxing
+
+Sesi is designed to run and orchestrate untrusted AI reasoning pipelines. Because code can be influenced by prompt injections or generated model instructions, Sesi incorporates a **safe-by-default, zero-trust sandboxing engine**.
+
+### 🛡️ Core Security Features
+
+1. **Safe-by-Default Execution**:
+   - Sesi's sandbox is **enabled by default**. Any standard Sesi interpreter execution blocks system command lines (`exec`, `spawn`) and locks down imports and paths.
+   - *Overriding Safety:* Developers can explicitly bypass safe mode programmatically by initializing the interpreter with options, or on the command line by setting `SESI_SAFE_MODE=false`.
+
+2. **Absolute Prototype Pollution Immunity**:
+   - Sesi uses **prototype-free objects (`Object.create(null)`)** for all object literals, JSON parses (`from_json` or `std/json`), and structured model responses inside the interpreter.
+   - Because these objects do not inherit from standard JavaScript prototypes and possess no `__proto__` or prototype chain, **prototype pollution is physically and architecturally impossible**.
+
+3. **Strict Path Whitelisting**:
+   - Sesi validates all filesystem and subprocess paths against a **strict directory whitelist** (by default, only the Current Working Directory and the Script's base directory are allowed).
+   - Any path traversal resolving outside the whitelist is instantly rejected with a `Security Violation` exception.
+
+4. **Automated LLM Tool Call Sanitization**:
+   - Even if safe mode is explicitly turned off for developer automation, Sesi **strictly blocks automated tool execution** of sensitive commands (like `exec` and `spawn`) when requested dynamically by the model via `tool_call`. This completely isolates the host from prompt-injection RCE.
+
+5. **Deep isolation & Map Cloning**:
+   - Sub-interpreters loaded via concurrent workflows (`multi_req`) are fully isolated. Sesi **deep-clones** prompts and memories, preventing concurrent agent tasks from leaking state or polluting each other.
+
+### ⚙️ Programmatic Embedding Configurations
+When embedding Sesi inside a host application, you can statically configure safety settings directly in code:
+```typescript
+const interpreter = new Interpreter(scriptDir, {
+  safeMode: true,        // Enable full sandbox limits (on by default)
+  allowLocalFs: false,  // Block directory escapes (on by default)
+  allowedPaths: ['/var/tmp/sandbox'] // Custom strict whitelist directories
+});
+```
+
 ## Documentation
 
 - [Getting Started](https://github.com/Misterscan/Sesi/blob/main/QUICKSTART.md)
@@ -74,11 +134,11 @@ print code
 - [Language Specification](https://github.com/Misterscan/Sesi/blob/main/docs/SPECIFICATION.md)
 - [Language Comparison Showcase](https://github.com/Misterscan/Sesi/blob/main/docs/COMPARISON.md)
 - [Built-in Functions](https://github.com/Misterscan/Sesi/blob/main/docs/BUILTINS.md)
-- [Reasoning Guide](https://github.com/Misterscan/Sesi/blob/main/docs/SYSTEMS_REASONING.md)
-- [Distributed Systems](https://github.com/Misterscan/Sesi/blob/main/docs/DISTRIBUTED_SYSTEMS.md)
+- [Reasoning Guide](https://github.com/Misterscan/Sesi/blob/main/docs/REASONING.md)
+- [Concurrency Systems](https://github.com/Misterscan/Sesi/blob/main/docs/CONCURRENCY.md)
 - [Runtime Architecture](https://github.com/Misterscan/Sesi/blob/main/docs/ARCHITECTURE.md)
 
-## AI Agent Context
+## Agent Context
 
 The root-level `SKILLS.md` file is a workspace context file for AI agents. It records repo-specific constraints such as valid Sesi syntax expectations, execution conventions, and the intended meaning of directories like `main/` and `main/tests/`.
 
@@ -86,37 +146,83 @@ The root-level `SKILLS.md` file is a workspace context file for AI agents. It re
 
 ```
 Sesi/
-├── SKILLS.md             # AI-agent workspace context and repo guardrails
-├── index.html            # Sesi-generated landing page
-├── eslint.config.mjs     # ESLint configuration
-├── dist/                 # Compiled TypeScript output
-├── example.js            # Helper script to run basic examples
-├── example-ai.js         # Helper script to run Reasoning examples
-├── package.json          # Dependencies & scripts
-├── tsconfig.json         # TypeScript configuration
-├── QUICKSTART.md         # Quick start guide
-├── IMPLEMENTATION_SUMMARY.md # Progress and tracking
-├── src/
-│   ├── types.ts          # Type system & AST nodes
-│   ├── lexer.ts          # Tokenization
-│   ├── parser.ts         # AST generation
-│   ├── interpreter.ts    # Execution engine
-│   ├── builtins.ts       # Standard library
-│   ├── ai-runtime.ts     # Gemini integration
-│   └── index.ts          # Main entry point
+├── SKILLS.md                        # Workspace context and repo guardrails
+├── index.html                       # Sesi-generated systems landing page
+├── eslint.config.mjs                # ESLint configuration
+├── example.js                       # Helper script to run basic examples
+├── example-ai.js                    # Helper script to run reasoning examples
+├── examples.sesi                    # Central execution suite for examples
+├── README.md                        # Project overview
+├── QUICKSTART.md                    # Getting started guide
+├── package.json                     # Dependencies & scripts
+├── tsconfig.json                    # TypeScript configuration
+├── dist/                            # Compiled TypeScript output
+│
+├── src/                             # Source code
+│   ├── types.ts                     # Type definitions & AST nodes (400+ lines)
+│   ├── lexer.ts                     # Tokenization (350+ lines)
+│   ├── parser.ts                    # Recursive descent parser (700+ lines)
+│   ├── interpreter.ts               # Tree-walking interpreter (600+ lines)
+│   ├── builtins.ts                  # Built-in functions (250+ lines)
+│   ├── ai-runtime.ts                # Integrated reasoning integration (120+ lines)
+│   └── index.ts                     # Entry point (30+ lines)
+│
 ├── bin/
-│   └── sesi.js           # CLI executable
-├── examples/             # 18 sample programs demonstrating all features
-├── main/                 # Main entry and specialized tests
-│   ├── playground.sesi   # Main playground script
-│   ├── start.sesi        # Beginner script 
-│   ├── build_website.sesi # Sesi-powered landing page generator
-│   └── tests/            # Debug and syntax scripts
-├── tests/                # Test suite
-└── docs/                 # Documentation (ARCHITECTURE, BUILTINS, SPECIFICATION, etc.)
+│   └── sesi.js                      # CLI executable
+│
+├── main/                            # Playgrounds & debugging
+│   ├── playground.sesi              # Main playground script
+│   ├── start.sesi                   # Beginner script
+│   └── tests/                       # Additional syntax validation scripts
+│
+├── docs/
+│   ├── SPECIFICATION.md             # Complete language spec (600+ lines)
+│   ├── ARCHITECTURE.md              # Runtime & system design (400+ lines)
+│   ├── BUILTINS.md                  # Built-in functions reference (450+ lines)
+│   ├── COMPARISON.md                # Language comparison showcase
+│   ├── CONCURRENCY.md               # Concurrency & coordination guide (>100 lines)
+│   ├── IMAGE_GENERATION.md          # Image generation guide (>100 lines)
+│   ├── REASONING.md                 # Reasoning and simple logic guide (>500 lines)
+│   ├── ROADMAP.md                   # V2-V4+ development plan (400+ lines)
+│   └── sesi_ai_chronicles.md        # AI project history & notes
+│
+├── examples/
+│   ├── 01_hello.sesi                # Hello World
+│   ├── 02_variables.sesi            # Variables & operations
+│   ├── 03_functions.sesi            # Functions with parameters
+│   ├── 04_conditionals.sesi         # If/else control flow
+│   ├── 05_loops.sesi                # While, for, for-in loops
+│   ├── 06_arrays_objects.sesi       # Collections
+│   ├── 07_prompts.sesi              # Reasoning blocks
+│   ├── 08_model_call.sesi           # Basic reasoning calls
+│   ├── 09_structured_output.sesi    # Type-safe reasoning responses
+│   ├── 10_code_generation.sesi      # Systems logic generation
+│   ├── 11_memory_conversation.sesi  # Multi-turn stateful reasoning
+│   ├── 12_classification.sesi       # Systems classification loop
+│   ├── 13_data_pipeline.sesi        # Complete systems pipeline
+│   ├── 14_folder_explainer.sesi     # Directory parsing & reasoning
+│   ├── 15_image_generation.sesi     # Image generation API test
+│   ├── 16_modules.sesi              # Modules & std library namespaces
+│   ├── 17_http_client.sesi          # Network GET/POST client
+│   ├── 18_parallel_requests.sesi    # Parallel requests concurrency
+│   ├── 19_search_web.sesi           # Web search integration
+│   ├── 20_model_aliases.sesi        # Custom model naming aliases
+│   ├── 21_custom_tools.sesi         # Custom runtime tool definitions
+│   └── 22_reasoning_plus_custom_tools.sesi # Reasoning composed with custom tools
+│
+└── tests/                           # Engine test suite
+    ├── basic.test.ts                # Core parsing & evaluation tests
+    ├── cache.test.ts                # Execution caching tests
+    ├── http.test.ts                 # Web request builtins testing
+    ├── module.test.ts               # Imports & module loading tests
+    ├── parallel.test.ts             # Concurrent execution tests
+    ├── security.test.ts             # Sandbox & guardrail tests
+    ├── test-gemini.ts               # Base model integration test
+    ├── test-gemini2.ts              # Extended model integration test
+    └── workflow.test.ts             # Complex sequence workflows tests
 ```
 
-## Version 1.2 Features (In Progress)
+## Version 1.3 Features (In Progress)
 
 ### Core Language ✅
 
@@ -170,4 +276,4 @@ Sesi/
 
 ## License
 
-MIT
+MIT