// WASM Tool Sandbox Interface
//
// Defines the contract between sandboxed tools and the host runtime.
// Tools export the `tool` interface; the host provides the `host` interface.

package near:agent;

/// Host-provided capabilities for sandboxed tools.
///
/// These are the only ways a sandboxed tool can interact with the outside world.
/// The set is intentionally minimal to reduce attack surface.
interface host {
    /// Log levels for structured logging.
    enum log-level {
        trace,
        debug,
        info,
        warn,
        error,
    }

    /// Emit a log message.
    ///
    /// Messages are collected and emitted after execution completes.
    /// Rate-limited to 1000 entries per execution, 4KB per message.
    log: func(level: log-level, message: string);

    /// Get the current timestamp in milliseconds since Unix epoch.
    now-millis: func() -> u64;

    /// Read a file from the workspace (if capability granted).
    ///
    /// Path must be relative (no leading /) and cannot contain "..".
    /// Returns None if the file doesn't exist or capability not granted.
    workspace-read: func(path: string) -> option<string>;
}

/// Tool interface that sandboxed tools must implement.
interface tool {
    /// Request payload for tool execution.
    record request {
        /// JSON-encoded parameters matching the tool's schema.
        params: string,
        /// Optional JSON-encoded job context for stateful operations.
        context: option<string>,
    }

    /// Response from tool execution.
    record response {
        /// JSON-encoded result on success.
        result: option<string>,
        /// Error message on failure.
        error: option<string>,
    }

    /// Execute the tool with the given request.
    ///
    /// This is the main entry point. The tool should:
    /// 1. Parse params as JSON according to its schema
    /// 2. Perform the operation
    /// 3. Return a response with either result or error set
    execute: func(req: request) -> response;

    /// Get the JSON Schema for this tool's parameters.
    ///
    /// Must return a valid JSON Schema object describing the expected
    /// structure of the `params` field in requests.
    schema: func() -> string;

    /// Get a human-readable description of what this tool does.
    ///
    /// Used by the LLM to understand when to invoke the tool.
    description: func() -> string;
}

/// World definition for sandboxed tools.
///
/// Tools import host capabilities and export the tool interface.
world sandboxed-tool {
    import host;
    export tool;
}