⌕

Sesi Runtime Architecture

Overview

Sesi is a concise and highly legible programming language. It uses a clean tree-walking interpreter model built in TypeScript. The architecture is optimized for simplicity and eliminating the need for async/await syntax or heavy module imports. By acting as a minimal orchestration layer, Sesi allows developers to write clean, straightforward logic that natively handles background processes and API or Reasoning calls without SDK overhead.

Component Stack

┌─────────────────────────────────────────────┐
│         Sesi Program (.sesi file)           │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│      Lexer (src/lexer.ts)                   │
│  Converts source text → Tokens              │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│      Parser (src/parser.ts)                 │
│  Converts Tokens → Abstract Syntax Tree     │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│      Interpreter (src/interpreter.ts)       │
│  Tree-walking interpreter                   │
│  - Evaluates expressions                    │
│  - Executes statements                      │
│  - Manages scopes/environments              │
└──────┬───────────────────────┬──────────────┘
       │                       │
       │                       │
┌──────▼──────────────┐  ┌────▼────────────────┐
│ Builtins            │  │ AI Runtime          │
│ (src/builtins.ts)   │  │ (src/ai-runtime.ts) │
│                     │  │                     │
│ - print()           │  │ - Gemini API calls  │
│ - len()             │  │ - Memory mgmt       │
│ - read_file()       │  │ - Structured output │
│ - write_file()      │  │ - Tool calling      │
│ - spawn()           │  │                     │
│ - exec()            │  │                     │
│ - time()            │  │                     │
│ - random()          │  │                     │
│ - etc.              │  │                     │
└─────────────────────┘  └────┬────────────────┘
                              │
                    ┌─────────▼──────────┐
                    │  Gemini API        │
                    │  (@google/genai)   │
                    └────────────────────┘

Execution Flow

1. Lexical Analysis (Lexer)

Input: Source code string
Process: Character-by-character tokenization

- Identifier and keyword recognition

- Number and string literal parsing

- Operator and delimiter recognition

- Comment stripping

Output: Token stream

Example:

Source: let x = 10
Tokens: [LET, IDENTIFIER("x"), EQUAL, NUMBER(10), EOF]

2. Parsing (Parser)

Input: Token stream
Process: Recursive descent parsing

- Statement parsing (declarations, control flow)

- Expression parsing (operators, function calls, Reasoning constructs)

- AST construction

- Error recovery

Output: Abstract Syntax Tree (AST)

Example AST Node:

{
  type: 'LetStatement',
  name: 'x',
  value: {
    type: 'Literal',
    value: 10,
    rawType: 'number'
  }
}

3. Interpretation (Interpreter)

Input: AST
Process: Recursive tree evaluation

- Statement execution in order

- Expression evaluation with proper operator precedence

- Environment/scope management with lexical scoping

- Blocking host-side async calls for Reasoning operations

- Control flow (return, break, continue)

Output: Program side effects (print, Reasoning calls, etc.)

Scope and Environment Management

Sesi uses lexical scoping with an environment chain:

┌─────────────────────────┐
│  Global Environment     │
│  - Built-in functions   │
│  - Global variables     │
└────────┬────────────────┘
         │
    ┌────▼────────────────┐
    │ Function Environment│
    │ - Parameters        │
    │ - Local variables   │
    └────┬────────────────┘
         │
    ┌────▼────────────────┐
    │  Block Environment  │
    │  - Block variables  │
    └─────────────────────┘

Environment Lookup

Check current environment
Walk up parent chain until found
If not found anywhere, error

Variable Assignment

Try to update in current scope
If not in current scope, try parent scopes
Update in the scope where variable was found

Type System

Sesi has a dynamic type system with runtime type checking:

RuntimeValue =
  | number
  | string
  | boolean
  | null
  | Array
  | Object
  | RuntimeFunction
  | RuntimeModule

Type Coercion Rules

String Concatenation (operator +):

"Hello" + 5        → "Hello5"
"Age:" 30          → "Age: 30"
any + string       → toString(any) + string
string + any       → string + toString(any)

Numeric Operations:

10 + 20            → 30
"10" + 20          → "1020" (not numeric!)
10 20              → "10 20" (not numeric!)

Truthiness:

null   → false
false  → false
0      → false
""     → false
[]     → true
{}     → true

Reasoning Integration

Reasoning Runtime Lifecycle

Initialization:

- Load @google/genai SDK

- Validate GEMINI_API_KEY environment variable

During Execution:

- Parse model calls from AST

- Construct prompt from string concatenation

- Make async API call to Gemini

Wait for response (blocking in v1.x)
Validate finish reason and non-empty text
Return text response to program or throw

Memory Management:

- Simple string buffers per memory ID

- Append/update operations

- Passed to next model call

Model Call Flow

ModelCallExpression (AST)
    │
    ├─ Evaluate prompt expression
    ├─ Extract configuration (`thinkingLevel`, `max_tokens`, `cache`, etc.)
    ├─ Call AIRuntime.callModel()
    │   │
    │   ├─ Create Gemini interaction request
    │   ├─ Send to Gemini API
    │   ├─ Wait for response
    │   ├─ Validate finish reason == STOP
    │   └─ Extract text from response
    │
    └─ Return text to program or throw

Error Handling (V1)

Sesi now has basic exception-style error handling in v1:

Parse Errors: Parser logs the error and synchronizes to continue parsing later statements.
Runtime Errors: Interpreter errors throw and can be caught with try/catch.
Built-in I/O Errors: read_file(), write_file(), and list_dir() throw on filesystem failure.
Reasoning Errors: model() throws when the SDK fails, when no text is returned
Structured Output: structured_output() attempts recovery, but currently logs parsing failures and returns {} if coercion still fails.

Memory Model

Stack

Local variables
Function parameters
Scope frames

Heap

Arrays (dynamic)
Objects (key-value maps)
Strings (immutable)

Reasoning Context

Conversation memory per memory ID
String buffers, not structured storage

Performance Characteristics

Operation	Time	Notes
Variable lookup	O(n)	n = scope depth
Array access	O(1)	Direct indexing
Object access	O(1)	Map lookup
Function call	O(1)	+ body execution
Model call	~2-5s	Depends on Gemini latency
Array iteration	O(n)	Foreach loop

Limitations (V1)

Interpreter Single-threaded: Each individual Sesi process is single-threaded.
Process-level Concurrency: Sesi uses a multi-process model via spawn() for concurrent task execution.
No optimization: No bytecode or JIT.
Simple type system: Runtime checking only.
No macro system: No compile-time code generation
No introspection: Can't inspect function bodies
Limited error info: Basic error messages

Future Architecture (V2+)

V2 Planned Improvements

Async/await syntax for concurrent Reasoning calls
Bytecode compiler for faster execution
Advanced error handling with stack traces
Streaming response support
Function composition and piping

V3+ Vision

Agent framework with state machines
Knowledge base integration
Advanced memory with embedding search
Multi-agent orchestration
Custom type definitions
Macro system

Code Organization

SKILLS.md                 # AI-agent workspace context and repo guardrails
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
examples.sesi             # Central execution suite for examples
package.json              # Dependencies & scripts
tsconfig.json             # TypeScript configuration
QUICKSTART.md             # Quick start guide
IMPLEMENTATION_SUMMARY.md # Progress and tracking
README.md                 # Project overview

src/
├── types.ts              # Type definitions and AST
├── lexer.ts              # Tokenization
├── parser.ts             # AST generation
├── interpreter.ts        # Execution engine
├── ai-runtime.ts         # Gemini integration
├── builtins.ts           # Built-in functions
└── index.ts              # Main entry point

bin/
└── sesi.js               # CLI executable

main/                     # Main user scripts and debugging
├── build_website.sesi    # Sesi-generated landing page builder
└── tests/                # Additional syntax validation scripts

examples/
├── 01_hello.sesi         # Basic example
├── 02_variables.sesi     # Variables & operations
├── 03_functions.sesi     # Functions with parameters
├── 04_conditionals.sesi  # If/else control flow
├── 05_loops.sesi         # Loops & iteration
├── 06_arrays_objects.sesi # Arrays & objects
├── 07_prompts.sesi       # Prompts and string templating
├── 08_model_call.sesi    # Basic Reasoning model calls
├── 09_structured_output.sesi # Schema-guided structured output with JSON recovery and empty-object fallback on failure
├── 10_code_generation.sesi   # Reasoning-powered code gen
├── 11_memory_storage.sesi # Memory storage
├── 12_classification.sesi    # Classification
├── 13_data_pipeline.sesi     # Pipeline demo
├── 14_folder_explainer.sesi  # Directory parsing & reasoning
├── 15_image_generation.sesi  # Image generation API test
├── 16_modules.sesi          # Modules & std library imports
├── 17_http_client.sesi      # HTTP GET/POST client
├── 18_parallel_requests.sesi # Parallel requests concurrency
├── 19_search_web.sesi        # Web search
├── 20_model_aliases.sesi     # Custom model naming via aliases
├── 21_custom_tools.sesi      # Runtime custom tool definitions
├── 22_reasoning_plus_custom_tools.sesi # Compose reasoning with custom tools
├── 23_file_conversion.sesi         # Document and media conversion via `convert()`
├── 24_http_server.sesi             # Native async HTTP server (`listen`)
├── 25_webpage_server.sesi          # High-performance dynamic HTML site rendering
├── 26_database.sesi                # Embedded Document Database (`std/db`) crud operations
└── 27_robust_web_db.sesi           # Secured combined API server backed by persistent DB

docs/
├── SPECIFICATION.md      # Language spec
├── ARCHITECTURE.md       # This file
├── BUILTINS.md           # Built-in reference
├── CLI.md                # Comprehensive CLI & Parametric Eval guide
├── IMAGE_GENERATION.md   # Image generation guide
├── COMPARISON.md         # Language comparison showcase
├── REASONING.md          # Reasoning and simple logic guide
└── ROADMAP.md            # Future plans

tests/
├── 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

Workspace Context File

The root-level SKILLS.md file is part of the practical repo architecture. It is not consumed by the Sesi runtime, but it is intended to guide AI-assisted development in this workspace.

Testing Strategy

Unit Tests (per component):

// Lexer: tokenization correctness
// Parser: AST structure correctness
// Interpreter: evaluation correctness
// AI Runtime: Gemini integration

Integration Tests:

// Full program execution
// Complex Reasoning workflows
// Error handling

Example Programs:

Basic arithmetic and control flow
Functions and scoping
Arrays and objects
Reasoning model calls
Structured output parsing
Memory-based conversations

Debugging

Debug Output

Enable debug statement tracing:

SESI_DEBUG=1 sesi program.sesi

AST Visualization

Print the pretty-printed AST tree:

sesi --ast program.sesi

Token Stream

Print the scanned token stream table:

sesi --tokens program.sesi

Conclusion

Sesi's architecture prioritizes clarity and simplicity over performance. The tree-walking interpreter is ideal for:

Easy debugging
Simple extensions
Clear control flow
Smooth Reasoning integration

As the language matures, optimizations can be added without changing the API.