oino-extension 1.0.0

//! Guest SDK for Oino WASM component extensions (`oino:extension@2.0.0`).
//!
//! An extension is a type implementing [`Extension`]; [`export_extension!`] turns it into a
//! component. `init` registers events, tools, commands, shortcuts, flags, services, settings,
//! renderers and arbiter roles through [`Init`]; handlers are plain async closures or methods
//! receiving `&'static Self`. Host capabilities are thin typed wrappers over the WIT imports:
//!
//! | Module | WIT | Use |
//! |---|---|---|
//! | [`session`] | `session` | entries, `append_entry`, `send_message`, sessions index |
//! | [`control`] | `control` | model, thinking, tools, commands, compaction, command-context ops |
//! | [`models`] | `models` | completions, streaming, summaries, credentials |
//! | [`ui`] | `ui`, `registry` | dialogs, slots (panels, widgets, status, turn footers), settings namespaces, editor, OS integration; node trees from [`ui::widgets`] |
//! | [`agents`] | `agents` | nested agent sessions (subagents) |
//! | [`process`] | `process` | `exec`, spawn with streaming stdio, signals, process trees |
//! | [`tasks`] | `tasks` | host background tasks |
//! | [`http`] | `http` | fetch (streaming), loopback listener |
//! | [`fs`] | `fs` + WASI | named preopens, atomic writes, locks, watchers |
//! | [`timers`] | `timers` | `oino_timer` events, `sleep`, wall clock |
//! | [`kv`] | `kv` | scoped key-value state |
//! | [`settings`] | `registry` | extension settings reads and writes |
//! | [`secrets`], [`bus`], [`services`] | same | secrets, pub/sub, inter-extension calls |
//! | [`host_service`] | `host-service` | embedding-host services (`"browser"`, `"cron"`, …) |
//! | [`host`] | `host-info`, `log` | platform, workspace, env, logging |
//! | [`provider`] (feature `provider`) | `provider`, `provider-host` | provider components |
//!
//! ```ignore
//! use oino_extension::prelude::*;
//!
//! #[derive(Default)]
//! struct Hello;
//!
//! #[derive(Deserialize, JsonSchema)]
//! struct Args { name: String }
//!
//! impl Extension for Hello {
//!     async fn init(&'static self, cx: &mut Init<Self>) -> Result<()> {
//!         cx.tool(Tool::new("hello").description("Greets").args::<Args>()
//!             .run(|_ext, args: Args, _cx| async move { Ok(ToolResult::text(format!("Hello {}", args.name))) }));
//!         cx.on(EventKind::AgentEnd, |_ext, _ev, cx| async move {
//!             session::append_entry("hello.seen", Some(&json!({"session": cx.session_id()})))?;
//!             Ok(())
//!         });
//!         Ok(())
//!     }
//! }
//!
//! oino_extension::export_extension!(Hello);
//! ```

//!
//! # Errors
//!
//! Every wrapper returning [`Result`] fails only with the `host-error` of its WIT import
//! (permission denied, stale context, invalid argument, …) or a JSON decoding error, surfaced
//! as [`Error`]. Individual functions therefore do not repeat an `# Errors` section.

#![allow(
    clippy::missing_errors_doc,
    reason = "errors are documented once at crate level"
)]
#![cfg_attr(not(target_arch = "wasm32"), allow(dead_code, unused_imports))]

#[allow(
    unsafe_code,
    clippy::all,
    clippy::pedantic,
    missing_docs,
    unreachable_pub,
    reason = "generated by wit-bindgen"
)]
#[doc(hidden)]
pub mod bindings {
    #[cfg(feature = "provider")]
    wit_bindgen::generate!({
        path: "wit/oino-extension",
        world: "provider-extension",
        generate_all,
        pub_export_macro: true,
        export_macro_name: "export_guest",
        default_bindings_module: "oino_extension::bindings",
    });
    #[cfg(not(feature = "provider"))]
    wit_bindgen::generate!({
        path: "wit/oino-extension",
        world: "extension",
        generate_all,
        pub_export_macro: true,
        export_macro_name: "export_guest",
        default_bindings_module: "oino_extension::bindings",
    });
}

pub mod agents;
pub mod bus;
pub mod command;
pub mod context;
pub mod control;
mod error;
pub mod events;
pub mod fs;
pub mod host;
pub mod host_service;
pub mod http;
mod init;
pub mod kv;
pub mod models;
pub mod process;
#[cfg(feature = "provider")]
pub mod provider;
#[doc(hidden)]
pub mod rt;
pub mod secrets;
pub mod services;
pub mod session;
pub mod settings;
pub mod sync;
pub mod tasks;
pub mod timers;
pub mod tool;
pub mod ui;

/// Raw generated WIT types (escape hatch).
pub use bindings::oino::extension as wit;
pub use error::{Error, Result};
pub use futures;
pub use init::{Extension, Init};
pub use oino_ai;
pub use oino_extension_macros::tool;
pub use schemars;
pub use serde;
pub use serde_json;
pub use wit_bindgen;

/// Everything an extension usually needs.
pub mod prelude {
    pub use crate::command::{Command, Flag, Shortcut};
    pub use crate::context::{CommandCtx, Ctx, ToolCtx};
    pub use crate::events::{Event, EventKind};
    pub use crate::tool::{Tool, ToolKind, ToolResult};
    pub use crate::{
        Error, Extension, Init, Result, agents, bus, control, fs, host, http, kv, models, process,
        secrets, services, session, tasks, timers, ui,
    };
    pub use schemars::JsonSchema;
    pub use serde::{Deserialize, Serialize};
    pub use serde_json::{Value, json};
}

/// Exports an [`Extension`] type as the component's guest implementation.
///
/// ```ignore
/// oino_extension::export_extension!(MyExtension);
/// ```
#[macro_export]
macro_rules! export_extension {
    ($ty:ty) => {
        #[doc(hidden)]
        type __OinoExtensionShim = $crate::rt::Shim<$ty>;
        $crate::bindings::export_guest!(__OinoExtensionShim with_types_in $crate::bindings);
    };
}