convostatus
INSPECTION: View the current infrastructure stack for a session
Returns the current state of the user's infrastructure design including:
**Components** - Selected infrastructure services (VPC, databases, caching, etc.)
• Shows what services the user has chosen (e.g., PostgreSQL, Redis, S3)
• Includes architecture decisions (EKS vs EC2, monolith vs microservices)
**Config** - Configuration details for each component
• Database sizes, replica counts, storage amounts
• Cache settings, queue configurations
• Backup schedules and retention policies
**Pricing** - Cost estimates (when available)
• Monthly cost estimates per component
• Total estimated monthly spend
**Phase Indicators** - Where the user is in the design workflow:
• hasComponents: User has selected infrastructure services
• hasConfig: User has configured component details
• hasPricing: Cost estimates have been calculated
• hasTerraform: Ready for Terraform generation
Use this tool when the user asks 'what is my current stack?', 'show my infrastructure', 'what have I selected?', or similar questions about their design progress.
REQUIRES: session_id from convoopen response (format: sess_v2_...).
credawait
Wait for the user to securely connect their cloud account and subscribe to Luther Systems.
Polls until credentials appear on the session.
🎯 USE THIS TOOL WHEN: tfdeploy returns an 'auth_required', 'no_credentials', or 'credentials_expired' error.
The user needs to visit the connect URL to:
1. Connect their cloud credentials (AWS or GCP)
2. Sign up and subscribe to a Luther Systems plan (required for deployment)
This secure connection allows InsideOut to deploy and manage infrastructure in the user's cloud account on their behalf. Credentials are handled securely and only used for deployment and management sessions.
WORKFLOW:
1. FIRST: Present the connect URL and explanation to the user (from the tfdeploy error response)
2. THEN: Call this tool to begin polling for credentials
3. The user opens the URL in their browser to subscribe and add credentials
4. When credentials are found, inform the user and call tfdeploy to deploy
IMPORTANT: Do NOT call this tool without first showing the connect URL to the user. The user needs to see the URL to complete the process.
REQUIRES: session_id from convoopen response (format: sess_v2_...).
OPTIONAL: cloud ('aws' or 'gcp'), timeout (integer, seconds to wait, default 300, max 600).
gcpinspect
INSPECTION: Inspect GCP infrastructure for a deployed project
⚠️ **PREREQUISITE**: This tool requires a prior deployment ATTEMPT (successful or failed).
Check convostatus for hasDeployAttempt=true before calling. Works even after failed deploys to inspect orphaned resources.
Inspect deployed GCP resources after a deployment attempt.
Use this tool when the user asks about the status or details of their deployed GCP infrastructure.
It fetches temporary read-only credentials securely and queries the GCP API directly.
RESPONSE TIERS (default is summary for token efficiency):
- Summary (default): Key fields only (~500 tokens). Set detail=false, raw=false or omit both.
- Detail: Full metadata for a specific resource. Set detail=true + resource filter.
- Raw: Complete unprocessed API response. Set raw=true.
REQUIRES: session_id from convoopen response (format: sess_v2_...).
Supported services: apigateway, bastion, billing, cloudarmor, cloudbuild, cloudcdn, cloudfunctions, cloudkms, cloudlogging, cloudmonitoring, cloudrun, cloudsql, compute, firestore, gcs, gke, identityplatform, loadbalancer, memorystore, pubsub, secretmanager, vertexai, vpc
For a specific service's actions, call with action="list-actions".
METRICS: Use list-metrics to see available Cloud Monitoring metrics for any service (no credentials needed — progressive disclosure). Use get-metrics to retrieve time-series data. Optional filters JSON: {"hours":6,"period":300}.
Label breakdowns: Cloud Functions (by status), Load Balancer/API Gateway (by response_code_class), Cloud CDN (by cache_result).
Secret Manager get-metrics returns operational health (version count, replication, create time) — no time-series.
Bastion is an alias for Compute Engine metrics (SSH connection count not available as a GCP metric).
BILLING: Use service=billing to inspect GCP billing. Actions: get-billing-info (check if billing enabled, which billing account), get-budgets (list budget alerts for the project — auto-fetches billing account). Requires roles/billing.viewer IAM role.
Required IAM roles: Monitoring Viewer (roles/monitoring.viewer) for metrics, Secret Manager Viewer (roles/secretmanager.viewer) for secret health, Billing Viewer (roles/billing.viewer) for billing.
EXAMPLES:
- gcpinspect(session_id=..., service="compute", action="list-instances")
- gcpinspect(session_id=..., service="gke", action="list-clusters")
- gcpinspect(session_id=..., service="cloudsql", action="get-metrics", filters="{\"hours\":6}")
- gcpinspect(session_id=..., service="billing", action="get-billing-info")
gcpinspect_batch
BATCH INSPECTION: run up to 32 GCP inspect probes in one call.
⚠️ **PREREQUISITE**: Same as gcpinspect — deploy attempt required.
Check convostatus for hasDeployAttempt=true before calling.
Use this when you need to check more than ~3 resources. The backend fetches
Oracle credentials ONCE per batch and fans out probes against a single GCP
credentials blob — a 12-resource health check is ~5–8× faster and 12× fewer
Oracle round-trips than calling gcpinspect 12 times.
BUDGETS:
- Up to 32 sub-probes per call (subs array length).
- 30s per-sub timeout; 60s total batch wall-clock.
- Concurrency cap 8.
- 512 KB response cap: subs past the cap keep their envelope
(index/service/action/ok) but have result replaced with truncated=true.
PARTIAL FAILURE IS EXPECTED. The response is an ordered results array;
each entry has {index, service, action, ok, result, error}. Inspect each
result — do NOT abort on the first error. A credential fetch failure
leaves cred-less probes (list-actions, list-metrics) succeeding anyway.
REQUIRES: session_id from convoopen response (format: sess_v2_...).
Supported services: apigateway, bastion, billing, cloudarmor, cloudbuild, cloudcdn, cloudfunctions, cloudkms, cloudlogging, cloudmonitoring, cloudrun, cloudsql, compute, firestore, gcs, gke, identityplatform, loadbalancer, memorystore, pubsub, secretmanager, vertexai, vpc
For a specific service's actions, use gcpinspect (singular) with
action="list-actions" — batch is not the place for discovery.
Batch responses are always summarized (no detail/raw per-sub); use
singular gcpinspect when you need full metadata or raw API output for one
resource.
EXAMPLES:
- gcpinspect_batch(session_id=..., subs=[
{"service":"compute","action":"list-instances"},
{"service":"gke","action":"list-clusters"},
{"service":"cloudsql","action":"list-instances"}])
- gcpinspect_batch(session_id=..., subs=[
{"service":"compute","action":"get-metrics","filters":"{\"hours\":6}"},
{"service":"cloudrun","action":"get-metrics","filters":"{\"hours\":6}"}])
help
Get workflow guidance for using InsideOut infrastructure tools.
Call help() for a compact overview, or help(section=...) for a detailed guide.
Sections: workflow, tools, examples, inspect.
Responses include hints with next_actions and related_tools.
stackdiff
Structured diff between two stack versions.
Shows component-level changes (added/removed/modified), field-level details, and pricing deltas.
Optional `from_version` (defaults to latest applied) and `to_version` (defaults to current draft).
REQUIRES: session_id from convoopen response (format: sess_v2_...).
stackrollback
Create a draft version by reverting to a previous version's config.
Copies components, config, and pricing from the target version. If a draft already exists, updates it in-place (single-draft rule).
Use `stackversions` first to find available version numbers.
REQUIRES: session_id from convoopen response (format: sess_v2_...), version (target version number).
stackversions
List all stack versions for a session (newest first).
Shows version history including version number, status (draft/confirmed/applied), change summaries, and timestamps.
Use this tool to see the design history, review what changed between iterations, or find a version number to roll back to.
REQUIRES: session_id from convoopen response (format: sess_v2_...).
submit_feedback
FEEDBACK: Submit feedback, bug reports, or feature requests to Luther Systems
Use this tool to forward user feedback directly to the Luther Systems team. This includes bug reports, feature requests, questions, or general feedback about InsideOut.
The agent itself can also use this tool to report issues it encounters during operation.
REQUIRES: session_id, category, message
OPTIONAL: user_email (for follow-up), user_name, source (default: 'mcp'), initiator ('user' or 'agent')
Categories: bug_report, feature_request, general_feedback, question, security
The 'initiator' field tracks who triggered the report:
- 'user' — the user explicitly reported the issue or requested feedback submission
- 'agent' — Riley detected an issue and initiated the feedback flow
Examples:
- User says 'the deploy button is broken' → submit_feedback(category='bug_report', message='...', initiator='user')
- User says 'I wish it had dark mode' → submit_feedback(category='feature_request', message='...', initiator='user')
- Deployment failed with Terraform error → submit_feedback(category='bug_report', message='Deployment failed: Terraform apply error on aws_alb resource — timeout waiting for ALB provisioning', initiator='agent')
tfdeploy
WORKFLOW: Step 4 of 4 - Deploy infrastructure to the cloud
Deploy infrastructure by starting a Terraform job for an InsideOut session.
This tool initiates the actual deployment process after Terraform files have been generated.
IMPORTANT: This starts a long-running job (15+ minutes). Use tfstatus to monitor progress.
SINGLE-FLIGHT: only one TF job (apply/plan/destroy/drift) runs per session at a time. If another job is already in flight, tfdeploy returns tf_job_conflict with the live job_id — attach with tfstatus/tflogs instead of retrying, or pass force_new=true to override.
Returns confirmation that the deployment has started.
REQUIRES: session_id from convoopen response (format: sess_v2_...).
OPTIONAL: plan_id (string) — Apply a previously created plan from tfplan.
Preview-then-apply workflow: tfplan → tflogs (review) → tfdeploy(plan_id=...).
OPTIONAL: sandbox (boolean, default false) — deploys real generated Terraform. Set to true for cheap sandbox template (testing only).
OPTIONAL: ignore_drift (boolean, default false) - when true, proceeds with deploy even if infrastructure drift is detected. By default, deploys fail on drift. Use after reviewing drift details via tfdrift or tflogs.
OPTIONAL: force_new (boolean, default false) - bypass the session-level single-flight guard. Use only when the existing run is provably wedged.
CREDENTIAL FLOW (if credentials are missing):
1. Response includes a connect_url — present it to the user
2. Call credawait(session_id=...) to poll for credentials
3. When credawait returns success, retry tfdeploy
Do NOT call credawait without first showing the connect URL to the user.
tfdestroy
DESTROY: Tear down previously deployed infrastructure
Destroys infrastructure by calling the Oracle destroy endpoint for a session that has a prior successful deployment.
IMPORTANT: This starts a long-running job. Use tfstatus/tflogs to monitor progress.
SINGLE-FLIGHT: only one TF job per session at a time. If another job is already in flight, tfdestroy returns tf_job_conflict with the live job_id — attach with tfstatus/tflogs, or pass force_new=true to override.
REQUIRES: session_id from convoopen response (format: sess_v2_...).
OPTIONAL: force_new (boolean, default false) - bypass the single-flight guard. Use only when the existing run is provably wedged.
PREREQUISITE: The session must have a prior successful deployment with a project_id.
After destroy completes, the session is kept for historical record but hasDeployment is set to false.
tfdrift
DRIFT CHECK: Run a read-only drift detection check
Checks whether deployed infrastructure has drifted from the expected Terraform state.
This is a read-only operation — it does NOT modify any infrastructure.
Returns job_id. Use tflogs to stream the drift check results.
SINGLE-FLIGHT: only one TF job per session at a time. If another job is already in flight, tfdrift returns tf_job_conflict with the live job_id — attach with tfstatus/tflogs, or pass force_new=true to override.
REQUIRES: session_id from convoopen response (format: sess_v2_...).
PREREQUISITE: The session must have a prior deployment with a project_id.
OPTIONAL: force_new (boolean, default false) - bypass the single-flight guard. Use only when the existing run is provably wedged.
If drift is detected, the user can either fix the drift or use tfdeploy(ignore_drift=true) to proceed.
tfgenerate
WORKFLOW: Step 3 of 4 - Generate Terraform files from completed design
Generate Terraform files from an InsideOut session that has completed infrastructure design.
⚠️ PREREQUISITE: Only call this AFTER convoreply returns with `terraform_ready=true` in the response metadata.
DO NOT call this while convoreply is still running or before terraform_ready is confirmed!
If you get 'session has not reached terraform-ready state', wait for convoreply to complete first.
🎯 USE THIS TOOL WHEN: convoreply has returned with terraform_ready=true, OR the user asks to 'see the terraforms', 'generate terraform', 'show me the code', etc.
**DEFAULT RESPONSE**: Returns summary table + download URL (keeps code out of LLM context).
**FALLBACK**: Set `include_code: true` to get full code inline if curl/unzip fails.
**CRITICAL WORKFLOW** (default mode):
1. Call this tool to get file summary and download URL
2. ASK the user: 'Where would you like me to save the Terraform files? Default: ./insideout-infra/'
3. WAIT for user confirmation before running the download command
4. Run the curl/unzip command with the user's chosen directory
5. If curl/unzip FAILS (sandbox, security, platform issues), retry with `include_code: true`
**AFTER GENERATION**: Ask user if they want to review the files and then deploy with tfdeploy
REQUIRES: session_id from convoopen response (format: sess_v2_...).
OPTIONAL: include_code (boolean) - set true to return full code inline as fallback.
💡 TIP: Examine workflow.usage prompt for more context on how to properly use these tools.
tflogs
MONITORING: Fetch Terraform deployment logs with pagination
Fetches logs from a running or completed Terraform deployment job.
For **completed jobs**: uses REST endpoint for instant retrieval (supports `tail` for server-side filtering).
For **running jobs**: streams via SSE with timeout-based pagination.
**PAGINATION** (running jobs only): Use `last_event_id` from the response to fetch more:
1. First call: `tflogs(session_id='...')` → get logs + `last_event_id`
2. Next call: `tflogs(session_id='...', last_event_id='...')` → get NEW logs only
3. Repeat until `complete: true` in response
**RESPONSE FIELDS**:
- `logs`: Array of log messages collected
- `last_event_id`: Pass this back to get more logs (pagination cursor, SSE only)
- `complete`: true if job finished, false if more logs may be available
- `total_logs`: total log entries before tail truncation
REQUIRES: session_id from convoopen response (format: sess_v2_...).
OPTIONAL: job_id to target a specific deployment (use tfruns to discover IDs),
timeout (default 50s, max 55s), last_event_id (for pagination), tail (return only last N entries)
⚠️ CONTEXT WARNING: Deploy logs can be hundreds of lines. Use tail: 50 for completed jobs to avoid blowing up the context window.
tfoutputs
INSPECTION: Retrieve Terraform outputs from a completed deployment
Returns structured output values (VPC IDs, endpoints, cluster names, etc.) after a successful deploy.
Sensitive outputs are redacted (shown as '(sensitive)').
By default returns outputs for the latest successful deploy. Optionally specify job_id to get outputs for a specific deployment.
REQUIRES: session_id from convoopen response (format: sess_v2_...).
OPTIONAL: job_id (specific deployment), lifecycle (filter by step e.g. 'cloud-provision').
tfplan
PREVIEW: Run terraform plan to preview infrastructure changes
Runs a terraform plan for an InsideOut session without applying any changes.
This lets the user review what will be created/changed/destroyed before committing.
Returns job_id, plan_id, and project_id. Use tflogs to stream the plan output.
After the plan completes, use tfdeploy with plan_id to apply the exact plan.
SINGLE-FLIGHT: only one TF job per session at a time. If another job is already in flight, tfplan returns tf_job_conflict with the live job_id — attach with tfstatus/tflogs, or pass force_new=true to override.
REQUIRES: session_id from convoopen response (format: sess_v2_...).
OPTIONAL: sandbox (boolean, default false) — plans real generated Terraform. Set to true for cheap sandbox template (testing only).
OPTIONAL: force_new (boolean, default false) - bypass the single-flight guard. Use only when the existing run is provably wedged.
CREDENTIAL HANDLING: Same as tfdeploy - credentials must be configured first.
tfruns
INSPECTION: List all Terraform deployment runs for a session
Returns job IDs, statuses, types (apply/destroy), and timestamps for every run.
Use this to see deployment history, find job IDs for log inspection, or check which deployments succeeded or failed.
REQUIRES: session_id from convoopen response (format: sess_v2_...).
tfstatus
MONITORING: Quick status check for Terraform deployments
Check the current status of a Terraform deployment job.
Use this tool to quickly check if a deployment is running, completed, or failed.
Returns job status, job_id, and other metadata without streaming logs.
Use tflogs to stream the actual deployment logs.
REQUIRES: session_id from convoopen response (format: sess_v2_...).
OPTIONAL: job_id to target a specific deployment (use tfruns to discover IDs).
**LIVENESS**: The response carries two distinct timestamps:
- `updated_at` — last semantic change (only bumped when status / drift / version actually differ).
Useful for sorting deployments; NOT a per-poll heartbeat.
- `last_refresh_at` — last successful Oracle decode (stamped on every poll where reliable
reached Oracle, even if nothing in the row changed). Use this to confirm reliable is
still actively talking to Oracle for a long-running RUNNING job. Absent on rows that
haven't been refreshed since the column was added.
💡 TIP: Examine workflow.usage prompt for more context on how to properly use these tools.