RichScripts AI Action SDK 0.4.0 — developer preview

FILES
README.txt: start here after extracting the ZIP.
QuickStart.html: working local "Show status" example; no model calls.
richscripts-actions.js: dependency-free browser component.
index.html: local scripted support inbox demonstration; no model calls.
images/: screenshots used by the packaged demo page.
server-sample/: runnable classic ASP.NET/.NET Framework 4.5+ source files.
The website offers handler sources as .txt downloads; the ZIP places them in
server-sample/ using their .ashx/.aspx/.cs names. Install only in an authenticated host.

QUICK START
Load the JS file, add <div id="assistant"></div>, call RichScriptsActions.mount.
Supply actions [{name, description, parameters, readOnly, execute}] and either:
- resolve: async ({message, actions}) => ({action, arguments}) or {message};
- endpoint: a same-origin URL, csrfToken: a token string or getter.
The server endpoint receives JSON {message}, not a browser-owned tool catalog.
The server response can include proposalId for your execution adapter.
execute(args, context) receives context.proposalId; send it to your backend
executor on a confirmed write instead of trusting browser-owned arguments.

API
mount returns {submit(text), cancel(), getState(), clear(), destroy(), version}.
getState returns {busy,pending,destroyed}. cancel dismisses an unexecuted proposal.
After destroy you can mount again on the same host element.
Resolvers have a default 20-second timeout; timeoutMs accepts 100–120000.
Custom resolve receives an AbortSignal. Observe it to stop abandoned inference.
Execution callbacks have no automatic timeout or retry: failed/timed-out writes
can still have side effects, so check server state before a manual retry.
submit resolves false for a failed read execution as well as failed resolution.
submit returns a Promise<boolean>; it refuses concurrent requests and requests
while a confirmation is pending. clear refuses busy or pending state.
onEvent receives {phase,action,time}; it does not include user messages or arguments.
Use callbacks to connect your own durable audit logging.
Flat schemas support string/minLength/maxLength/enum, integer/minimum/maximum,
boolean and required fields. Unknown fields are rejected. This is not a full
JSON Schema validator. Unsupported argument types are rejected.
Only actions marked readOnly:true run without confirmation. Do not mark writes
as read-only. Confirmation in the browser is UX, not a server authorization gate.

ASP.NET SAMPLE
Configure AIActionApiKey and AIActionModel in protected web.config appSettings.
Choose a model that supports Responses API function tools and strict schemas.
No model is selected by default. The sample caps output at 150 tokens, disables
parallel tool calls and uses store:false. Short caps can truncate a proposal;
invalid proposals fail without executing anything. API inference still costs money.
Use your own key. Never put the key in browser code, storage or a public example.
The sample uses the OpenAI Responses API; alternative/local model providers need
a server-side adapter returning the same proposal contract.
GET /ActionResolver.ashx returns {csrfToken} for the authenticated session.
Bootstrap this once in your application and pass the returned token to the SDK.
POST verifies authentication, Origin, session CSRF token, body size and message
length. Limits are 10 calls/minute and 50/day PER SESSION for this sample.
Production needs durable account limits, tenant isolation and spend controls.

EXECUTION BOUNDARY — APPLICATION RESPONSIBILITY
The sample resolves proposals only; it has no database executor.
All callbacks that access real data must call your application's authenticated API.
Never execute generated JavaScript, model-supplied URLs, SQL or function bodies.
Use a server-owned action catalog and server-side parameter validation.
Resolve record identifiers under the authenticated user's tenant and permissions.
For writes, bind confirmation to a server-stored, expiring proposal. On confirmation
submit its ID; read the stored action and arguments on the server, verify user and
expiry, re-check permissions, consume once, and enforce a unique idempotency key.
The sample keeps up to 20 pending proposals per session, expiring after 5 minutes.
The resolver prunes expired entries and rejects a full queue BEFORE model inference.
ActionExecutor.ashx and ActionDemoState.cs execute ONLY fictional session records.
They bind proposals to the authenticated identity, revalidate server-owned arguments,
consume successful proposals and cache the last 20 results per session. Repeating an
ID returns its cached outcome without applying the change twice. Expired unexecuted
proposals return HTTP 410; unavailable IDs return HTTP 409. Different users are denied.
Session state locking serializes these handlers. Real applications must replace this
with tenant-scoped permissions, database transactions and durable idempotency.
The SDK recognizes optional ISO expiresAt and dismisses expired confirmation cards.
The server is authoritative; client clocks and browser checks are not authorization.
An unchecked browser "confirmed:true" flag is NOT sufficient approval enforcement.
Log durable outcomes; return the actual execution result to the component.
The prototype has no multi-turn model history, streaming, nested schema support,
real customer account integration, production billing or database execution.

PRIVACY
Demo data is memory-only and resets on reload. A connected resolver sends the
typed request to your own server and chosen model provider. Display that behavior
to your users. Supply only context needed for the action; avoid sensitive records.

REFERENCE
https://developers.openai.com/api/docs/guides/function-calling

Evaluation prototype. Commercial licensing and support terms are not yet published.

AUTHENTICATED ENDPOINT BOOTSTRAP EXAMPLE
const response = await fetch('/ActionResolver.ashx', {credentials:'same-origin'});
if (!response.ok) throw new Error('Sign in before mounting the assistant.');
const {csrfToken} = await response.json();
// Pass csrfToken to mount({endpoint:'/ActionResolver.ashx', csrfToken, actions}).
// Registered callbacks handle each response using your application API.
// Example write callback:
// execute: async (args, context) => {
//   const r = await fetch('/your-app/execute-proposal', {
//     method:'POST', credentials:'same-origin',
//     headers:{'Content-Type':'application/json','X-CSRF-Token':csrfToken},
//     body:JSON.stringify({proposalId:context.proposalId})
//   });
//   if(!r.ok) throw new Error('Execution failed');
//   return (await r.json()).message;
// }
// Use ActionExecutor.ashx for the fictional connected sample only.
// /your-app/execute-proposal for real data is still an APPLICATION endpoint
// you must implement. Follow EXECUTION BOUNDARY above.

CONNECTED ASP.NET SAMPLE INSTALLATION
The ZIP server-sample/ folder contains runnable source with the correct filenames:
ActionResolver.ashx, ActionExecutor.ashx, ConnectedDemo.aspx, richscripts-actions.js,
App_Code/ActionDemoState.cs, App_Code/ActionProposalStore.cs, and web.config.example.txt (settings to MERGE).
Requires .NET Framework 4.5+, System.Web.Extensions, session state and an existing
authenticated application. Install in that application's folder, not a new empty
unauthenticated site. There is no login system or production account provider in
this starter. Resolve and execute both return HTTP 401 for anonymous callers.
Do not replace your app's web.config. Merge the two model settings only, protect
the key and select a function-tool-capable model. Keep your existing authentication.
Open ConnectedDemo.aspx while signed in. GET bootstraps CSRF and loads the fictional
inbox. Typing invokes the configured model; read actions load matches and confirmed
writes update session data. No messages are sent and no customer database is touched.
Session expiration loses records and receipts. Demo note capacity is 100 per session.
Execution receives {proposalId} only; cancellation adds operation:"cancel".
Browser-supplied action names and arguments are rejected.
The CSRF token rotates when the authenticated identity changes. Each proposed
action has its own ID; preparing one in another tab does not overwrite earlier ones.
Expired entries may be pruned; a missing/consumed proposal returns HTTP 409.
Failures never cause automatic retries of writes. Inspect state before retrying.
The HTTP handlers have been compiled and core execution behavior tested; provider
inference and real IIS authentication integration require testing in your own app.

SERVER CANCELLATION
onCancel(context) is optional. The connected sample sends
{proposalId:context.proposalId, operation:'cancel'} to ActionExecutor.ashx.
It removes that user's stored proposal. Cancellation never executes an action.
Cancellation of an executed ID returns HTTP 409; it cannot undo a completed write.
The SDK cancels the local card immediately. A callback failure displays a warning
that server retirement was not confirmed. Cancellation does not automatically retry.
Server-side expiry remains enforced. Keep onCancel failures visible to your users.
Each tab has an independent UI; same-session pending proposals share a 20-item cap.
The sample cache holds 20 completed results. Evicted consumed IDs cannot execute again.


APPLICATION INTEGRATION WALKTHROUGH
Complete ZChat and MyLiveChat integration, testing, deployment and verification:
https://richscripts.com/ai-action-sdk-integration/
Download includes React component and classic ASP.NET dashboard adapter.
These real-app adapters use local command parsing; no LLM calls or writes.
The ASP.NET model/fictional-session sample is a separate integration path.