TypeStack Magic – Agent prompt & file operations

TypeStack Magic sends a single field (sQuestion) to the backend. The AgentPrompt class interprets this field in different modes:

  • TEST / PING – connectivity tests (no filesystem).
  • FILE-TEST – built-in filesystem test (safe sandbox).
  • JSON with aOperations – open, read, modify and save files, create pages, inspect the environment, etc.
  • Echo – fallback mode; no file operations.

All responses are JSON and include a high-level status plus detailed debug information for each operation.

1. Bases: app, web and core

File operations are always performed relative to a logical base path, controlled by sBase:

  • app – application root ($_SESSION['TypeStack']['sApplicationRoot']).
    Used for internal data and agent logs, typically one level above the public web root.
  • web – current web root (DirectAdmin-aware).
    Uses $_SERVER['DOCUMENT_ROOT'] where possible, or falls back to public_html / private_html under the application root.
  • core – core root ($_SESSION['TypeStack']['sCoreRoot']).
    Intended for read-only access to the shared core.

You select the base per operation via "sBase": "app", "sBase": "web" or "sBase": "core".

2. Prompt modes in AgentPrompt

2.1 TEST / PING

If the trimmed prompt equals TEST or PING, the Agent enters test mode (no filesystem access). 

TEST

Typical response:

{ "bSuccess": true, "sMode": "test", "sMessage": "AgentPrompt test route OK.", "sQuestion": "TEST", "aDebug": [ "Mode: test", "Time: 2025-12-04 23:59:59", "Note: this route never touches the filesystem." ]
}

2.2 FILE-TEST

If the prompt equals FILE-TEST, the Agent performs a simple write operation in the app base. 

FILE-TEST

The Agent will:

  1. Construct an operation for data/agent/fs-test.txt under sBase = "app".
  2. Treat it as overwrite with a timestamped string.
  3. Call ProcessFileOperation(), which internally uses AgentToolFileSystem::ReadFile() and AgentToolFileSystem::WriteFile().

The response contains a single entry in aOpResults with full debug info, including the resolved path and file size. On disk, the file appears under the application root, for example: 

/home/typest19/domains/typestack.com/data/agent/fs-test.txt

2.3 JSON (aOperations)

If the prompt starts with {, the Agent attempts to decode it as JSON. If the JSON contains aOperations as an array, each entry is one operation (filesystem, page, env, …).

2.4 Echo mode

For all other prompts, the Agent returns an echo-mode response without touching the filesystem: 

{ "bSuccess": true, "sMode": "echo", "sMessage": "AgentPrompt echo mode – no JSON detected, no file operations executed.", "sQuestion": "your original prompt..."
}

Echo mode is useful to see exactly what the server received, without side-effects.