<h1 align="center">Sesi: A Concise, Legible Programming Language</h1>

<p align="center">
  <em>Pronounced "say-see" — What you say, you'll see.</em>
</p>

<p align="center">
  <img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg">
  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-Ready-blue?logo=typescript">
  <img alt="Powered by Gemini" src="https://img.shields.io/badge/Powered%20By-Google%20Gemini-orange">
  <img alt="Framework" src="https://img.shields.io/badge/Node.js-Engine-success?logo=node.js">
</p>

<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. It is a language built for clarity.
</p>

<p align="center">
  <a href="https://code-with-sesi.netlify.app/">Homepage</a>
</p>

## SESI IS **NOT** AN AI WRAPPER LANGUAGE. IT IS **NOT** AN AI-NATIVE PROGRAMMING LANGUAGE. IT IS A GENERAL-PURPOSE PROGRAMMING LANGUAGE WITH **OPTIONAL** AI CAPABILITIES BUILT-IN. STRONG EMPHASIS ON **OPTIONAL**.

## Quick Start

Run any program directly:

```bash
# Standard script execution
sesi examples/main/01_hello.sesi

# Run script with arguments
sesi main/tests/test_args.sesi arg1 arg2

# Reasoning script example
sesi examples/optional/08_model_call.sesi

# Run all examples
sesi examples.sesi
```

Useful CLI shortcuts:

```bash
# Evaluate a quick snippet
sesi -e "print 'hello'"
```

```bash
# Ask the built-in co-pilot a question
sesi -h "how do I use memory?"
```

```bash
# Ask for help about a specific file
sesi examples/main/01_hello.sesi -h "what is this script doing?"
```

```bash
# Encrypt or decrypt a script file manually
sesi -enc my_script.sesi -p "my-password"
sesi -dec my_script.sesi -p "my-password"
```

To avoid exposing passwords in your shell's history, you can set the `SESI_PASSWORD` environment variable in your `.env` file (or your system's shell environment).

```bash
export SESI_PASSWORD="my-password"
# Encrypt or decrypt automatically using SESI_PASSWORD environment variable
sesi -enc my_script.sesi
sesi -dec my_script.sesi
```

```bash
# Run with sandbox restrictions disabled
sesi examples/main/01_hello.sesi -l
```

# Local Execution (Development)

If you are developing inside the repository or haven't installed `sesi` globally, use the npm scripts:

```bash
# Run a Sesi script
npm run sesi -- examples/main/01_hello.sesi
```

```bash
# Evaluate an inline snippet
npm run sesi:eval "print 'Sesi running!'"
```

```bash
# Ask Sesi's Co-Pilot
npm run sesi:help "how to make a directory?"
```

```bash
# Encrypt / Decrypt scripts (uses SESI_PASSWORD from your .env automatically)
npm run sesi:encrypt "secret.sesi"
npm run sesi:decrypt "secret.sesi"
```

```bash
# Run classic examples
npm run example examples/main/01_hello.sesi
npm run example:ai examples/optional/08_model_call.sesi
npm run example:all
```

## Language Overview

Sesi is designed for developers who want to:

- Write normal code (variables, functions, loops, etc.)
- Call Reasoning directly within code using `prompt` and `model` blocks
- Get structured outputs from Reasoning with type guarantees
- Build Reasoning agents with memory and multi-step reasoning
- Maintain full control and transparency

## Example

```sesi
// Basic computation
let x = 10
let y = 20
let result = x + y
print result // 30

// Reasoning-powered code generation
prompt generateCode {"Write a TypeScript function that reverses a string"}
let code = model("gemini-3.1-pro-preview") {generateCode}
print code
```

## Security & Sandboxing

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](./QUICKSTART.md)
- [CLI Reference](./CLI.md)
- [Language Specification](./SPECIFICATION.md)
- [Language Comparison Showcase](./COMPARISON.md)
- [Built-in Functions](./BUILTINS.md)
- [Reasoning](./REASONING.md)
- [Runtime Architecture](./docs/ARCHITECTURE.md)

## Version 1.3 Features (In Progress)

### Core Language ✅

- **Variables & Bindings**: `let` for all bindings (const is deprecated).
- **Functions**: Side-effect driven functions with typed parameters.
- **Control Flow**: `if/else`, `while`, `for`, and `try/catch`.
- **Collections**: Robust Arrays and Objects.
- **Error Handling**: Structured `try/catch` for both runtime and Reasoning-level errors.
- **Local Module Imports/Exports**: Import custom local `.sesi` modules cleanly using relative import/export syntax!
- **Standard Library Modules**: Native support for imported standard libraries, including:
  - `std/math` (providing `PI`, `E`, `sqrt`, `pow`, `sin`, `cos`, etc.)
  - `std/time` (providing `sleep` and `now`)
  - `std/json` (providing JSON serialization/deserialization)

### Reasoning-Native Features ✅

- `model()` calls with Reasoning provider configuration
- `image()` calls with specific ratio/size generation capabilities
- **Async Polling**: Native looping to auto-resume generation when hitting `MAX_TOKENS` limit

### System Features ✅

- **Memory**: Basic memory for multi-turn reasoning
- **Filesystem I/O**: `read_file()`, `write_file()`, `to_json()`, `write_image()`, and `list_dir()` for local file I/O
- **Native Concurrency**: `spawn()` and `exec()` for concurrent process management, and `multi_req(array<function>)` for physical parallel request execution.
- **Logic Caching**: High-efficiency Sesi Logic Caching (`.sesi_cache.json`) for local call caching.
- **HTTP Client**: Built-in, native HTTP client support using `web_get(url)` and `web_send(url, body, headers)` with zero external dependencies.
- **Utility Builtins**: `time()` and `random()` for robust coordination
- **Structured Output**: `structured_output()` for typed JSON Schema
- **Function Calling**: `tool_call()` for function calling
- **Prompt Blocks**: `prompt` blocks for cleaner and more concise script composition

### Type System

- Static types: `number`, `string`, `bool`, `array<T>`, `object<T>`
- Type inference
- Union types for Reasoning response handling

## Roadmap

### V2: Advanced Reasoning

- Long-term memory and context management
- Custom tool definitions
- Streaming responses

### V3: Agents & Orchestration

- Agent definitions with state
- Tool composition and chaining
- Multi-agent collaboration
- Persistent knowledge bases

## License

MIT
