super-agent-bedrock 0.5.0__tar.gz

super_agent_bedrock-0.5.0/LICENSE

@@ -0,0 +1,196 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but not
+      limited to compiled object code, generated documentation, and
+      conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions to that
+      Work or Derivative Works thereof, that is intentionally submitted to
+      Licensor for inclusion in the Work by the copyright owner or by an
+      individual or Legal Entity authorized to submit on behalf of the
+      copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent to
+      the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of this
+      License, each Contributor hereby grants to You a perpetual, worldwide,
+      non-exclusive, no-charge, royalty-free, irrevocable (except as stated
+      in this section) patent license to make, have made, use, offer to sell,
+      sell, import, and otherwise transfer the Work, where such license
+      applies only to those patent claims licensable by such Contributor that
+      are necessarily infringed by their Contribution(s) alone or by
+      combination of their Contribution(s) with the Work to which such
+      Contribution(s) was submitted. If You institute patent litigation
+      against any entity alleging that the Work or a Contribution incorporated
+      within the Work constitutes direct or contributory patent infringement,
+      then any patent licenses granted to You under this License for that Work
+      shall terminate as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the Work or
+      Derivative Works thereof in any medium, with or without modifications,
+      and in Source or Object form, provided that You meet the following
+      conditions:
+
+      (a) You must give any other recipients of the Work or Derivative Works
+          a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works that
+          You distribute, all copyright, patent, trademark, and attribution
+          notices from the Source form of the Work, excluding those notices
+          that do not pertain to any part of the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained within
+          such NOTICE file, excluding those notices that do not pertain to any
+          part of the Derivative Works, in at least one of the following
+          places: within a NOTICE text file distributed as part of the
+          Derivative Works; within the Source form or documentation, if
+          provided along with the Derivative Works; or, within a display
+          generated by the Derivative Works, if and wherever such third-party
+          notices normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License. You may
+          add Your own attribution notices within Derivative Works that You
+          distribute, alongside or as an addendum to the NOTICE text from the
+          Work, provided that such additional attribution notices cannot be
+          construed as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and may
+      provide additional or different license terms and conditions for use,
+      reproduction, or distribution of Your modifications, or for any such
+      Derivative Works as a whole, provided Your use, reproduction, and
+      distribution of the Work otherwise complies with the conditions stated
+      in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work by
+      You to the Licensor shall be under the terms and conditions of this
+      License, without any additional terms or conditions. Notwithstanding the
+      above, nothing herein shall supersede or modify the terms of any
+      separate license agreement you may have executed with Licensor regarding
+      such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed to
+      in writing, Licensor provides the Work (and each Contributor provides
+      its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
+      OF ANY KIND, either express or implied, including, without limitation,
+      any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY,
+      or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for
+      determining the appropriateness of using or redistributing the Work and
+      assume any risks associated with Your exercise of permissions under this
+      License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise, unless
+      required by applicable law (such as deliberate and grossly negligent
+      acts) or agreed to in writing, shall any Contributor be liable to You
+      for damages, including any direct, indirect, special, incidental, or
+      consequential damages of any character arising as a result of this
+      License or out of the use or inability to use the Work (including but
+      not limited to damages for loss of goodwill, work stoppage, computer
+      failure or malfunction, or any and all other commercial damages or
+      losses), even if such Contributor has been advised of the possibility of
+      such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing the
+      Work or Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may act only on Your own behalf and on
+      Your sole responsibility, not on behalf of any other Contributor, and
+      only if You agree to indemnify, defend, and hold each Contributor
+      harmless for any liability incurred by, or claims asserted against, such
+      Contributor by reason of your accepting any such warranty or additional
+      liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include the
+      brackets.) The text should be enclosed in the appropriate comment
+      syntax for the file format. We also recommend that a file or class
+      name and description of purpose be included on the same "printed page"
+      as the copyright notice for easier identification within third-party
+      archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

super_agent_bedrock-0.5.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include docs *.md

super_agent_bedrock-0.5.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: super-agent-bedrock
+Version: 0.5.0
+Summary: SUPER AGENT: a Bedrock-backed AWS and Kubernetes operations assistant
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3<2,>=1.34
+Requires-Dist: botocore<2,>=1.34
+Requires-Dist: rich<15,>=13
+Provides-Extra: kubernetes
+Requires-Dist: kubernetes<34,>=28; extra == "kubernetes"
+Provides-Extra: ui
+Requires-Dist: prompt-toolkit<4,>=3; extra == "ui"
+Dynamic: license-file
+
+# SUPER AGENT
+
+SUPER AGENT is a conversational AWS and Kubernetes operations assistant that
+uses the Amazon Bedrock Converse API. It can inspect resources, investigate
+metrics and logs, and perform guarded operations after explicit approval.
+
+## How to run
+
+```bash
+python -m pip install super-agent-bedrock
+super-agent
+```
+
+Ask a one-off question:
+
+```bash
+super-agent "List EKS clusters in us-west-2"
+```
+
+Or start an interactive session:
+
+```bash
+super-agent --interactive
+```
+
+Check this machine's AWS identity, Bedrock model access, and Kubernetes client
+readiness before starting work:
+
+```bash
+super-agent --preflight
+```
+
+Interactive sessions run this credential-safe check at startup. Use
+`--skip-preflight` only when you deliberately want to suppress its display;
+it does not disable runtime safety checks. Within an interactive session, run
+`/doctor` to repeat the check.
+
+Choose a model or AWS Region when needed:
+
+```bash
+super-agent --model <model-or-profile-id> --region eu-west-1 "Show EC2 instances"
+```
+
+## Cross-account operations
+
+Cross-account is a first-class workflow. Select the target account and SUPER
+AGENT assumes its `CrossAccountAgentRole` by default, verifies the resulting
+STS identity is in that exact account, and displays the target in the terminal
+footer and audit log.
+
+```bash
+super-agent --account-id 123456789012
+super-agent --account-id 123456789012 --role-name Platform/CrossAccountAgentRole
+super-agent --account-id 123456789012 --external-id your-trust-policy-value --preflight
+```
+
+`--assume-role` remains available for an explicit role ARN. The source role
+must be allowed to call `sts:AssumeRole`, and the target role's trust policy
+must allow the source role. An account mismatch stops the session before any
+Bedrock or infrastructure operation begins.
+
+Inside an interactive session, switch safely without exiting:
+
+```text
+/account 219826436331
+```
+
+You can also type `switch account to 219826436331`. SUPER AGENT asks for
+approval, verifies the newly assumed identity, then clears the previous
+conversation and Kubernetes connection so evidence from two accounts cannot
+mix.
+
+## JEV tool safety
+
+JEV is the local validation layer between the model and AWS. It blocks unknown
+or sensitive APIs so a model cannot guess an invalid operation or read a secret
+just because it is technically a “read” call. The catalog expands through
+reviewed typed tools and validated capabilities. It includes CloudTrail event
+lookup for “who created this?” investigations and CloudWatch Logs group
+discovery; unsupported services are intentionally rejected with an explanation
+rather than executed blindly.
+
+## Development architecture
+
+For contributors, [the architecture guide](docs/ARCHITECTURE.md) explains the
+runtime flow, JEV boundaries, and the safe module-extraction order.
+
+## Requirements
+
+- Python 3.9 or later
+- AWS credentials supplied by a standard AWS profile, IAM Identity Center,
+  environment variables, an EC2 instance profile, or an EKS web-identity role
+- Amazon Bedrock model access and `bedrock:InvokeModel` permission for the
+  selected model and Region
+
+Install Kubernetes support when you need Kubernetes API tools:
+
+```bash
+python -m pip install "super-agent-bedrock[kubernetes]"
+```
+
+## Safety
+
+Read-only operations run without confirmation. Operations that create, change,
+restart, scale, delete, or send commands require approval. A built-in block
+list refuses destructive commands even when approval is supplied.
+
+The tool does not create AWS credentials, enable Bedrock model access, or
+change account-level permissions. Never put credentials, access keys, or
+tokens into source code, memory files, or package configuration.
+
+If Bedrock invocation is denied, preflight identifies the active AWS role,
+account, model or inference profile, and Region, then explains the smallest
+safe administrator checks. It never prints credential values. The readiness
+probe sends a fixed one-token request without conversation history solely to
+verify the selected model's Converse permission.
+
+## Troubleshooting documentation
+
+For AWS and Kubernetes investigations, SUPER AGENT can retrieve concise,
+cited guidance from official AWS and Kubernetes documentation. It only contacts
+allowlisted HTTPS documentation domains, uses bounded response sizes and
+timeouts, and never sends credentials or cookies. If documentation is
+unavailable, it reports the official source link rather than inventing advice.
+
+Interactive terminals use a color-aware Rich interface with a thinking/progress
+indicator. Set `NO_COLOR=1` or redirect output for plain text;
+`--json` always emits machine-readable JSON only.
+
+The interface uses a warm-coral `#D97757` accent for the SUPER AGENT wordmark,
+section headings, table headers, borders, prompts, and status
+indicator. Green, amber, red, and dim text are reserved for semantic success,
+approval/warning, errors, and secondary information. Color is optional: plain
+text and JSON remain complete and readable.
+
+Normal interactive use shows only a generic thinking indicator. Pass
+`--verbose` when you need sanitized tool names and activity diagnostics.
+Routine intermediate tool failures are kept out of the normal UI; the final
+answer explains only relevant evidence. Approval prompts show the requested
+action or command, rather than internal tool JSON.
+
+The terminal UI uses no emoji and falls back to plain text when output is
+redirected or `NO_COLOR` is set. It deliberately uses the lightweight standard
+input path, avoiding raw-terminal dependencies that can degrade performance in
+minimal EC2 and container environments.
+
+Use `/help` in an interactive session for `/status`, `/details`, `/theme`,
+`/doctor`, `/clear`, and `/exit`. Prefix an existing allowlisted local
+diagnostic with `!`, for example `! df -h`; this is not a general shell escape.
+
+For in-process history, slash-command completion, and keyboard navigation,
+install the optional UI extra. It is lazy-loaded and the normal input path is
+used automatically when the extra or a compatible terminal is unavailable.
+
+```bash
+python -m pip install "super-agent-bedrock[ui]"
+```
+
+## Audit log and fresh sessions
+
+SUPER AGENT stores a sanitized append-only audit log named `super_agent.log`
+in the directory where it is started. It records compact requests, outcomes,
+and tool status, but it is never sent to Bedrock as conversation history.
+
+On the first `0.3.4` run, an existing `ai_memory.dm` is renamed to a dated
+`ai_memory.dm.archived-...` backup. This stops old conversations from causing
+the model to resume a previous investigation. `/clear` clears only the current
+in-process session; the audit log remains intact.
+
+## SES email identities
+
+SUPER AGENT can create an Amazon SES email identity after explicit approval.
+That action asks AWS to send its verification email; it does not and cannot
+bypass the mailbox verification link. Ask the assistant to check the identity
+status after the link is used, then send email with a verified `from_email` or
+the `EMAIL_FROM` environment variable. Datadog is not part of this package.
+
+## EKS workload access
+
+SUPER AGENT runs safe diagnostics directly on the host where it is started.
+It uses SSM only for an explicitly selected different managed instance. To
+inspect Kubernetes namespaces, pods, events, logs, and deployments, install
+the Kubernetes extra and allow the agent to create/update local kubeconfig for
+the chosen EKS cluster. This connects through the Kubernetes API; it does not
+open an interactive SSH, SSM, or pod-exec session.
+
+Raw `kubectl` and raw `aws eks update-kubeconfig` commands are blocked by the
+deterministic JEV guard. After approved EKS connection, the agent uses typed
+Kubernetes API tools for Services, Ingresses, and Istio/Gateway API routing
+resources instead.
+
+Generic AWS SDK reads are also constrained to a bundled JEV capability catalog.
+Before an AWS request, SUPER AGENT validates the selected service, operation,
+and input parameters against the installed botocore service model. Unsupported
+operations and missing required parameters are rejected locally; every allowed
+catalog operation includes an official AWS Boto3 reference URL in its
+structured result.
+
+## Capacity and quota assessments
+
+Capacity and quota requests use a narrow, deterministic investigation plan.
+SUPER AGENT calculates EC2 vCPU and memory from `DescribeInstanceTypes`, reads
+the account's actual EC2 on-demand standard-vCPU quota from Service Quotas,
+and reads applied EKS quotas. After an approved EKS connection it calculates
+Kubernetes allocatable CPU, memory, pod slots, node conditions, and resource
+limit coverage through the typed Kubernetes API.
+
+It does not guess AWS quota defaults or infer capacity from instance-type
+names. If a quota, Kubernetes connection, or live Metrics Server data is not
+available, the response labels it unavailable. Normal output is limited to
+verified failures, measured utilization at or above 80%, and unavailable data.
+
+## EBS volumes
+
+SUPER AGENT can list EBS volumes with size, type, encryption, attachment, and
+attachment-time evidence. For a request such as “last usage,” it checks the
+most recent observed `VolumeReadOps` or `VolumeWriteOps` CloudWatch data in a
+bounded lookback period. This is reported as recent observed I/O, not as a
+permanent “last used” timestamp, because EBS does not provide one.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

super_agent_bedrock-0.5.0/README.md

@@ -0,0 +1,223 @@
+# SUPER AGENT
+
+SUPER AGENT is a conversational AWS and Kubernetes operations assistant that
+uses the Amazon Bedrock Converse API. It can inspect resources, investigate
+metrics and logs, and perform guarded operations after explicit approval.
+
+## How to run
+
+```bash
+python -m pip install super-agent-bedrock
+super-agent
+```
+
+Ask a one-off question:
+
+```bash
+super-agent "List EKS clusters in us-west-2"
+```
+
+Or start an interactive session:
+
+```bash
+super-agent --interactive
+```
+
+Check this machine's AWS identity, Bedrock model access, and Kubernetes client
+readiness before starting work:
+
+```bash
+super-agent --preflight
+```
+
+Interactive sessions run this credential-safe check at startup. Use
+`--skip-preflight` only when you deliberately want to suppress its display;
+it does not disable runtime safety checks. Within an interactive session, run
+`/doctor` to repeat the check.
+
+Choose a model or AWS Region when needed:
+
+```bash
+super-agent --model <model-or-profile-id> --region eu-west-1 "Show EC2 instances"
+```
+
+## Cross-account operations
+
+Cross-account is a first-class workflow. Select the target account and SUPER
+AGENT assumes its `CrossAccountAgentRole` by default, verifies the resulting
+STS identity is in that exact account, and displays the target in the terminal
+footer and audit log.
+
+```bash
+super-agent --account-id 123456789012
+super-agent --account-id 123456789012 --role-name Platform/CrossAccountAgentRole
+super-agent --account-id 123456789012 --external-id your-trust-policy-value --preflight
+```
+
+`--assume-role` remains available for an explicit role ARN. The source role
+must be allowed to call `sts:AssumeRole`, and the target role's trust policy
+must allow the source role. An account mismatch stops the session before any
+Bedrock or infrastructure operation begins.
+
+Inside an interactive session, switch safely without exiting:
+
+```text
+/account 219826436331
+```
+
+You can also type `switch account to 219826436331`. SUPER AGENT asks for
+approval, verifies the newly assumed identity, then clears the previous
+conversation and Kubernetes connection so evidence from two accounts cannot
+mix.
+
+## JEV tool safety
+
+JEV is the local validation layer between the model and AWS. It blocks unknown
+or sensitive APIs so a model cannot guess an invalid operation or read a secret
+just because it is technically a “read” call. The catalog expands through
+reviewed typed tools and validated capabilities. It includes CloudTrail event
+lookup for “who created this?” investigations and CloudWatch Logs group
+discovery; unsupported services are intentionally rejected with an explanation
+rather than executed blindly.
+
+## Development architecture
+
+For contributors, [the architecture guide](docs/ARCHITECTURE.md) explains the
+runtime flow, JEV boundaries, and the safe module-extraction order.
+
+## Requirements
+
+- Python 3.9 or later
+- AWS credentials supplied by a standard AWS profile, IAM Identity Center,
+  environment variables, an EC2 instance profile, or an EKS web-identity role
+- Amazon Bedrock model access and `bedrock:InvokeModel` permission for the
+  selected model and Region
+
+Install Kubernetes support when you need Kubernetes API tools:
+
+```bash
+python -m pip install "super-agent-bedrock[kubernetes]"
+```
+
+## Safety
+
+Read-only operations run without confirmation. Operations that create, change,
+restart, scale, delete, or send commands require approval. A built-in block
+list refuses destructive commands even when approval is supplied.
+
+The tool does not create AWS credentials, enable Bedrock model access, or
+change account-level permissions. Never put credentials, access keys, or
+tokens into source code, memory files, or package configuration.
+
+If Bedrock invocation is denied, preflight identifies the active AWS role,
+account, model or inference profile, and Region, then explains the smallest
+safe administrator checks. It never prints credential values. The readiness
+probe sends a fixed one-token request without conversation history solely to
+verify the selected model's Converse permission.
+
+## Troubleshooting documentation
+
+For AWS and Kubernetes investigations, SUPER AGENT can retrieve concise,
+cited guidance from official AWS and Kubernetes documentation. It only contacts
+allowlisted HTTPS documentation domains, uses bounded response sizes and
+timeouts, and never sends credentials or cookies. If documentation is
+unavailable, it reports the official source link rather than inventing advice.
+
+Interactive terminals use a color-aware Rich interface with a thinking/progress
+indicator. Set `NO_COLOR=1` or redirect output for plain text;
+`--json` always emits machine-readable JSON only.
+
+The interface uses a warm-coral `#D97757` accent for the SUPER AGENT wordmark,
+section headings, table headers, borders, prompts, and status
+indicator. Green, amber, red, and dim text are reserved for semantic success,
+approval/warning, errors, and secondary information. Color is optional: plain
+text and JSON remain complete and readable.
+
+Normal interactive use shows only a generic thinking indicator. Pass
+`--verbose` when you need sanitized tool names and activity diagnostics.
+Routine intermediate tool failures are kept out of the normal UI; the final
+answer explains only relevant evidence. Approval prompts show the requested
+action or command, rather than internal tool JSON.
+
+The terminal UI uses no emoji and falls back to plain text when output is
+redirected or `NO_COLOR` is set. It deliberately uses the lightweight standard
+input path, avoiding raw-terminal dependencies that can degrade performance in
+minimal EC2 and container environments.
+
+Use `/help` in an interactive session for `/status`, `/details`, `/theme`,
+`/doctor`, `/clear`, and `/exit`. Prefix an existing allowlisted local
+diagnostic with `!`, for example `! df -h`; this is not a general shell escape.
+
+For in-process history, slash-command completion, and keyboard navigation,
+install the optional UI extra. It is lazy-loaded and the normal input path is
+used automatically when the extra or a compatible terminal is unavailable.
+
+```bash
+python -m pip install "super-agent-bedrock[ui]"
+```
+
+## Audit log and fresh sessions
+
+SUPER AGENT stores a sanitized append-only audit log named `super_agent.log`
+in the directory where it is started. It records compact requests, outcomes,
+and tool status, but it is never sent to Bedrock as conversation history.
+
+On the first `0.3.4` run, an existing `ai_memory.dm` is renamed to a dated
+`ai_memory.dm.archived-...` backup. This stops old conversations from causing
+the model to resume a previous investigation. `/clear` clears only the current
+in-process session; the audit log remains intact.
+
+## SES email identities
+
+SUPER AGENT can create an Amazon SES email identity after explicit approval.
+That action asks AWS to send its verification email; it does not and cannot
+bypass the mailbox verification link. Ask the assistant to check the identity
+status after the link is used, then send email with a verified `from_email` or
+the `EMAIL_FROM` environment variable. Datadog is not part of this package.
+
+## EKS workload access
+
+SUPER AGENT runs safe diagnostics directly on the host where it is started.
+It uses SSM only for an explicitly selected different managed instance. To
+inspect Kubernetes namespaces, pods, events, logs, and deployments, install
+the Kubernetes extra and allow the agent to create/update local kubeconfig for
+the chosen EKS cluster. This connects through the Kubernetes API; it does not
+open an interactive SSH, SSM, or pod-exec session.
+
+Raw `kubectl` and raw `aws eks update-kubeconfig` commands are blocked by the
+deterministic JEV guard. After approved EKS connection, the agent uses typed
+Kubernetes API tools for Services, Ingresses, and Istio/Gateway API routing
+resources instead.
+
+Generic AWS SDK reads are also constrained to a bundled JEV capability catalog.
+Before an AWS request, SUPER AGENT validates the selected service, operation,
+and input parameters against the installed botocore service model. Unsupported
+operations and missing required parameters are rejected locally; every allowed
+catalog operation includes an official AWS Boto3 reference URL in its
+structured result.
+
+## Capacity and quota assessments
+
+Capacity and quota requests use a narrow, deterministic investigation plan.
+SUPER AGENT calculates EC2 vCPU and memory from `DescribeInstanceTypes`, reads
+the account's actual EC2 on-demand standard-vCPU quota from Service Quotas,
+and reads applied EKS quotas. After an approved EKS connection it calculates
+Kubernetes allocatable CPU, memory, pod slots, node conditions, and resource
+limit coverage through the typed Kubernetes API.
+
+It does not guess AWS quota defaults or infer capacity from instance-type
+names. If a quota, Kubernetes connection, or live Metrics Server data is not
+available, the response labels it unavailable. Normal output is limited to
+verified failures, measured utilization at or above 80%, and unavailable data.
+
+## EBS volumes
+
+SUPER AGENT can list EBS volumes with size, type, encryption, attachment, and
+attachment-time evidence. For a request such as “last usage,” it checks the
+most recent observed `VolumeReadOps` or `VolumeWriteOps` CloudWatch data in a
+bounded lookback period. This is reported as recent observed I/O, not as a
+permanent “last used” timestamp, because EBS does not provide one.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).